Authored by Claude Opus 4.7 (Claude Code) consuming @neo-gemini-pro's sunset-handoff — session A f5cf... (her #11519 commit cc348941b AC2 + AC3 partial); session B 39eee906-3fd4-424f-9348-828b46ece38c (this implementation completion).

FAIR-band: over-target [12/30] — taking this lane despite over-target because (a) operator-direction via sunset-handover Priority 1 designating #11519 to me, (b) @neo-gemini-pro explicitly yielded the lane via sunset comment IC_kwDODSospM8AAAABCmjkhw enumerating "Next Agent Tasks", (c) specialist-context (I authored the peer-role substrate-validation comment IC_kwDODSospM8AAAABCly8-w designing Option A in the prior session). Under-target peer (@neo-gemini-pro at 5/30) explicitly NOT a yield candidate — she's actively on #11500 per MESSAGE:0dc25f7f.

Resolves #11519

Closes the cross-daemon coverage gap from #11503 umbrella. Builds on @neo-gemini-pro's commit cc348941b (AC2 env-var inheritance + AC3 partial options.env injection); completes AC1 (Orchestrator wrap) + AC3 (onComplete invocation in runTask.clear()) + AC4 (PrimaryRepoSyncService cascade env forwarding) + AC5-AC8 spec tests + AC12 ADR.

Evidence: L2 (unit coverage across orchestrator wrap, lease primitive sync overloads, cascade env passing, cross-daemon contention, stale-env-token negative cases — 57/57 across 4 spec files) → L4 required (operator restart of npm run ai:orchestrator to validate the env-var inheritance contract under a real primary-dev-sync cascade). Residual: AC1 + AC4 host validation [#11519 Post-Merge Validation below].

What shipped

• AC1 — Orchestrator.createMaintenanceExecutor acquires the shared heavy-maintenance file lease before executing heavy tasks; releases via options.onComplete (child-spawned path), Promise.then settle (in-process async path), or immediate (sync-complete / spawn-failed paths). Cross-process contention surfaces via new recordCrossDaemonLeaseDeferral with reasonCode='heavy-maintenance-lease-held' — distinct from the in-process heavy-maintenance-backpressure taxonomy.
• AC3 — ProcessSupervisorService.runTask.clear() now invokes options.onComplete({code, error}) from both success and failure paths, wrapped in try/catch for hook-failure isolation (extends Gemini's options.env plumbing).
• AC4 — PrimaryRepoSyncService.runKbSync reads NEO_HEAVY_MAINTENANCE_LEASE_INHERITED_TOKEN from process.env and explicitly forwards via execFileSyncFn env option when set — prevents the self-defer hazard where the cascade kbSync child would see its parent primary-dev-sync's lease and defer with 'held'. When the env-var is absent, no env option is passed (default-inheritance behavior preserved, backward-compat).
• AC2/AC9 (Gemini's commit, preserved on rebase) — withHeavyMaintenanceLease honors NEO_HEAVY_MAINTENANCE_LEASE_INHERITED_TOKEN for parent→child inheritance; JSDoc returned-shape + acquisition-descriptor tables extended with the new 'inherited' row.
• Sync overloads — acquireHeavyMaintenanceLeaseSync + inspectHeavyMaintenanceLeaseSync + releaseHeavyMaintenanceLeaseSync added to keep the orchestrator wrapper synchronous (preserves orchestrator.poll() synchronous observability). Async surface unchanged for CLI consumers.
• Production-pollution defense — new resolveHeavyMaintenanceLeasePath() uses multi-tier fallback (this.heavyMaintenanceLeasePath → path.join(this.dataDir, 'heavy-maintenance-lease.json') → DEFAULT_HEAVY_MAINTENANCE_LEASE_PATH). Tests passing dataDir: '/tmp/orchestrator-test' via Neo.create get lease-path isolation even without configure() being called. Empirical anchor: pre-fix iteration contaminated the canonical .neo-ai-data/orchestrator-daemon/heavy-maintenance-lease.json during a test run; cleaned and the defensive derivation prevents recurrence.
• AC12 — ADR 0009-cross-daemon-lease-inheritance.md codifies the env-based parent→child inheritance contract, audit-trail rationale, and the 3 rejected alternative mechanisms (allowlist / forced-bypass / same-owner-string).

Deltas from ticket

• Sync overloads were not in the original AC; added because the alternative (making createMaintenanceExecutor async) broke the test contract that orchestrator.poll() is observable synchronously post-call. Sync overloads share buildLeasePayload + isLeaseStale + return-shape with the async path — only the IO seam differs. Smoke test pins sync-vs-async parity to prevent future drift.
• resolveHeavyMaintenanceLeasePath() defensive helper added beyond AC scope because the original use-site-time derivation would have polluted the canonical production lease path during unit-test runs. The helper isolates test runs to dataDir-derived paths automatically.

Substrate slot-rationale (per pull-request-workflow.md §1.1)

This PR touches learn/agentos/decisions/0009-cross-daemon-lease-inheritance.md (new ADR). Disposition table:

Test Evidence

npm run test-unit -- test/playwright/unit/ai/daemons/Orchestrator.spec.mjs \
                     test/playwright/unit/ai/daemons/services/HeavyMaintenanceLeaseService.spec.mjs \
                     test/playwright/unit/ai/daemons/services/PrimaryRepoSyncService.spec.mjs \
                     test/playwright/unit/ai/daemons/services/ProcessSupervisorService.spec.mjs

New tests added:

• HeavyMaintenanceLeaseService.spec.mjs: AC6 cascade-inheritance, AC8a (lease-file-missing), AC8b (token-mismatch), AC8c/AC7 (stale-replaced-parent), sync-overload parity smoke — 5 new tests (14 total).
• PrimaryRepoSyncService.spec.mjs: AC4 env passing + AC4 backward-compat (env-var absent) — 2 new tests (18 total).
• Orchestrator.spec.mjs: AC5 cross-daemon contention via dual orchestrators on shared leasePath — 1 new test (18 total); per-test unique lease path via testOrchestratorSeq counter prevents cross-test contamination + production pollution.

Post-Merge Validation

• Restart npm run ai:orchestrator in primary host checkout; confirm orchestrator boots cleanly and acquires the shared lease for the next due heavy task. Verify the lease file appears at .neo-ai-data/orchestrator-daemon/heavy-maintenance-lease.json during execution and is removed on completion.
• Trigger a primary-dev-sync task with a cascade kbSync; confirm the cascade child does NOT self-defer with 'held' (would surface as recordTaskOutcome('kbSync', 'skipped', {reasonCode: 'heavy-maintenance-lease-held'})). Expected: cascade kbSync completes via 'inherited' path.
• Start two concurrent orchestrator instances on the same dataDir (e.g., operator restart-overlap simulation); confirm the second instance defers heavy tasks with reasonCode='heavy-maintenance-lease-held' and holdingOwner identifying the first instance's task.

Commits

• cc348941b — feat(ai): add env and onComplete support to runTask for lease inheritance (#11519) (authored by @neo-gemini-pro, preserved through rebase + co-author trailer)
• 45b583c3b — feat(ai): orchestrator shared-lease wrap + cascade env inheritance (#11519) (authored by @neo-opus-ada)

Evolution

Notable shape pivots during implementation:

1. Async wrapper → sync wrapper with sync overloads. Initial implementation made createMaintenanceExecutor async to handle the await on acquireHeavyMaintenanceLease. This broke 6 existing tests that observe orchestrator.poll() synchronously. Two paths considered: (a) make all tests async-aware, (b) introduce sync overloads in the lease primitive. Path (b) preserved existing test contract + production behavior + introduced minimal new API surface; (a) would have rippled into every existing test pattern. Chose (b).

2. Use-site lease path resolution. Initial code set this.heavyMaintenanceLeasePath only in configure() (production-path) and assumed it via this.heavyMaintenanceLeasePath at use site. Tests that call poll() directly without start() bypassed configure() → fallback to DEFAULT_HEAVY_MAINTENANCE_LEASE_PATH → polluted the canonical production lease file. Cleaned the contamination and refactored to resolveHeavyMaintenanceLeasePath() helper with multi-tier fallback; tests inherit dataDir-derived paths automatically.

Related

• Parent epic: #11503 (Enforce heavy-maintenance mutex across Agent OS tasks)
• Substrate primitive: PR #11506 / #11505 (HeavyMaintenanceLeaseService)
• Sibling Lane A: PR #11514 / #11513 (orchestrator backup + cross-poll tests)
• Sibling Lane C: PR #11509 / #11507 (manual CLI script lease adoption)
• Sibling consumer-guidance: PR #11518 / #11515 (release-timing JSDoc extended here)
• Adjacent merged: PR #11525 / #11524 (MLX launch-model split — included via rebase; orthogonal scope)

Origin Session ID: 39eee906-3fd4-424f-9348-828b46ece38c

Co-Authored-By: Neo Gemini 3.1 Pro neo-gemini-pro@neomjs.com