Summary

• Problem: gateway singleton lock behavior under contention had limited startup observability and weaker stale-lock recovery signaling, making startup storms and stale-lock incidents harder to triage.
• Why it matters: parallel starts/restarts can happen in real use (daemon restarts, local relaunches, CI/e2e), and lock ambiguity increases false "already running" failures and operator confusion.
• What changed:
  • Added structured gateway lock telemetry events for acquire start/contention/stale recovery/success/timeout.
  • Hardened stale-lock recovery and lock lifecycle cleanup paths in acquireGatewayLock.
  • Wired explicit startup telemetry logs into gateway run-loop lock acquisition/reacquisition paths.
  • Added regression tests for macOS/Linux stale recovery paths and parallel startup storms.
  • Added AGENTS.local.md to .gitignore so local guardrails are never staged.
• What did NOT change (scope boundary):
  • No auth model or gateway network bind behavior changes.
  • No config schema/user-facing flags added.
  • No channel/business-logic routing changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #

User-visible / Behavior Changes

• Gateway startup now logs explicit singleton-lock lifecycle telemetry (acquire/wait/recovered/acquired/timeout).
• Under stale-lock conditions, lock recovery behavior is more deterministic and diagnosable.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No) (existing localhost port probe behavior only)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS (authoring), Linux lock paths covered in tests.
• Runtime/container: Node 22 + pnpm.
• Model/provider: N/A.
• Integration/channel (if any): Gateway core lock path.
• Relevant config (redacted): default local config path hashing + lock dir behavior.

Steps

1. pnpm format:check -- .gitignore src/infra/gateway-lock.ts src/infra/gateway-lock.test.ts src/cli/gateway-cli/run-loop.ts src/cli/gateway-cli/run-loop.test.ts
2. pnpm test -- src/infra/gateway-lock.test.ts src/cli/gateway-cli/run-loop.test.ts
3. pnpm build

Expected

• New telemetry tests pass.
• Parallel startup storm regression passes.
• Gateway lock + run-loop changes build and tests are green.

Actual

• Format check passed for touched files.
• Targeted tests passed (21/21).
• Build passed.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Evidence included via new/updated tests:

• src/infra/gateway-lock.test.ts
• src/cli/gateway-cli/run-loop.test.ts

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • lock telemetry flow (start -> contention -> stale recovery -> success)
  • lock reacquire path during restart in run-loop
  • stale lock handling on darwin-style and linux-style paths
  • parallel startup storm serialization and lock cleanup
• Edge cases checked:
  • malformed/unknown owner + stale timeout reclaim
  • owner dead reclaim path
  • startup timeout telemetry emission path
• What you did not verify:
  • full end-to-end multi-process gateway startup under external daemon orchestration beyond unit-level coverage.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • revert commits 3c4533239 and 4525a5a23
• Files/config to restore:
  • .gitignore
  • src/infra/gateway-lock.ts
  • src/infra/gateway-lock.test.ts
  • src/cli/gateway-cli/run-loop.ts
  • src/cli/gateway-cli/run-loop.test.ts
• Known bad symptoms reviewers should watch for:
  • unexpected lock timeout spam during normal single-instance startup
  • lock telemetry logs appearing without corresponding contention

Risks and Mitigations

• Risk:
  • False stale-lock reclaim in edge environments with unusual FS/stat behavior.
  • Mitigation:
    • Conservative stat fallback; reclaim only on explicit stale/dead signals; added regression coverage.
• Risk:
  • Increased startup log volume from telemetry.
  • Mitigation:
    • Concise single-line events emitted only on lock lifecycle transitions.

AI-assisted: Yes (Codex). Author reviewed resulting code and behavior.
Testing level: Fully tested for touched units + build.