docs(env): document DISPATCH_STALE_WORK_INTERVAL_MS

[itsmiso-ai]

Documented DISPATCH_STALE_WORK_INTERVAL_MS in .env.example (already in commit 5a61135) and hardened the npm audit script in package.json with fetch retries + timeout so the CI step rides out transient timeouts to the npm registry's audit endpoint instead of failing the whole…

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M3@https://litellm.jory.dev/v1 (anthropic) — routed smart (risk match: auth_changes)

Recommendation

Approve. This PR is a small, low-risk documentation/CI-hardening change. It adds the previously missing DISPATCH_STALE_WORK_INTERVAL_MS entry to .env.example and adds retry + timeout flags to the npm audit script in package.json so transient registry timeouts do not fail the CI step. No auth flow, session token handling, or production runtime code is altered.

Change-by-change findings

.env.example (+5/-0)

• The PR body notes the actual code change for DISPATCH_STALE_WORK_INTERVAL_MS is already on main in commit 5a61135. This PR only documents it.
• New entry matches the repository's existing scheduler-interval documentation style: env var name, comment explaining the interval, opt-out instructions, default value, and follows the DISPATCH_*_INTERVAL_MS convention.
• Placed correctly alongside the other scheduler interval variables (immediately after the DISPATCH_RECONCILE_INTERVAL_MS block and before the "Framework / build-time vars" divider).
• AGENTS.md Important Conventions table does not currently list DISPATCH_STALE_WORK_INTERVAL_MS. Optional follow-up: add a row to that table for full discoverability, but this is not required for merge.

package.json (+1/-1)

• Replaces npm audit --omit=dev --audit-level=high with npm audit --omit=dev --audit-level=high --fetch-retries=5 --fetch-timeout=120000 --fetch-retry-mintimeout=20000 --fetch-retry-maxtimeout=120000.
• Same audit level (high) and same --omit=dev filter are preserved, so the security posture is unchanged. Only network resilience flags are added.
• security-audit.yaml invokes npm run audit, so this hardening is picked up automatically.

Required checks

• review auth flow for regression — Verified: the diff touches only .env.example and the audit npm script. lib/auth.ts, lib/client-auth.ts, app/api/auth/*, the NextAuth/OIDC configuration, and the authorizeRequest / getAuthorizedActor call sites are all untouched. No auth code paths are added, removed, or modified. The .env.example change documents an existing scheduler interval; it does not introduce, rename, or deprecate any auth-related environment variable. No regression possible from this diff.
• verify session token handling is correct — Verified: no session token, bearer token, OAuth state, PKCE, cookie, or NEXTAUTH_SECRET handling is touched. DISPATCH_AGENT_TOKEN and NEXTAUTH_SECRET references in .env.example are unchanged. The package.json change affects only npm registry fetch behavior and does not interact with token storage, transmission, or verification. Session token handling is unaffected.

Standards Compliance

• No commit of secrets (AGENTS.md §Code Standards PR 6): Only .env.example is modified, and only a documentation comment plus a commented-out example value are added. No real secrets are introduced. Compliant.
• Environment Variables (AGENTS.md §Important Conventions): New variable name follows the DISPATCH_*_INTERVAL_MS family convention used by DISPATCH_RECONCILE_INTERVAL_MS, DISPATCH_SYNC_INTERVAL_MS, DISPATCH_GROOMER_INTERVAL_MS, DISPATCH_PR_FOLLOWUP_INTERVAL_MS, and DISPATCH_PRUNE_CLOSED_INTERVAL_MS. Default of 300000 (5 min) and "0" disables opt-out are consistent with the rest of the family. Compliant.
• API routes / Validation / Error handling / Prisma: Not applicable — no code in these areas is modified.
• GitHub Actions CI: npm audit still runs via .github/workflows/security-audit.yaml (AGENTS.md references it under §Security Accepted Risks). The hardening here makes that check more reliable. Compliant.
• AI review rules (.github/ai-review-rules.md): No OCI/digest changes, no risk-flag violations. Compliant.

CI Check Results

CI reached a terminal success state for the head commit before review: Build, Tests, Typecheck, Coverage, Database migrations, Lint, Database integration, Docker Build, Docker Build (MCP), npm audit, smoke — all green. The npm audit step in particular succeeded, which is the check most directly affected by this PR.

Unknowns or Needs Verification

None. The change is fully contained, documented, and CI-verified. The only optional follow-up (adding a DISPATCH_STALE_WORK_INTERVAL_MS row to the AGENTS.md environment variable table) is a non-blocking enhancement, not a correctness issue.

[its-saffron]

Info (docs): New DISPATCH_STALE_WORK_INTERVAL_MS entry matches the existing DISPATCH_*_INTERVAL_MS documentation style; consider also adding a row to the AGENTS.md environment-variable table for full discoverability (optional, non-blocking).

Automated finding from AI PR review.