Auto-Wakeup substrate semantic correction: fresh-session-spawn + boot-grounding prompt

Context

@tobiu corrected the strategic semantics of Sunset + Auto-Wakeup substrate verbatim 2026-05-02 morning:

"sunset is supposed to be final. meaning: all three harnesses CAN start fresh sessions easily. the goal is not to drop more messages into the sunsetted session, but to start a fresh one. ideally with a first prompt to read and follow the agents startup instructions first."

The currently-shipped substrate (Phase 1 #10602 + Phase 2 #10607) does the opposite — it keystroke-injects an in-place wake payload ("Auto-Wakeup Substrate: Resuming sunsetted session. Reason: ...") into the SAME chat that just executed sunset (Q1a per epic #10601 body). Per tobi's correction, the correct primitive is Q1b — open a fresh chat session (Cmd+N or harness equivalent) + paste a boot-grounding prompt instructing the new agent to read AGENTS_STARTUP.md first.

This ticket scopes the corrective work.

The Problem

Sequence of failures that landed the wrong substrate:

1. Epic #10601 body (my authoring) framed Q1a as "Phase 1 preferred" and Q1b as "Phase 3 fallback" — empirically inverted from the operator's actual intent.
2. PR #10607 Cycle 1 (Gemini authoring) shipped Q1b correctly (Cmd+N + paste). Functionally aligned with operator intent.
3. PR #10607 Cycle 1 review (my authoring) flagged "Q1a → Q1b unjustified scope shift" as BLOCKER #2 citing the (wrong) epic body framing. Forced Cycle 5 removal of Cmd+N.
4. PR #10607 Cycle 5+ shipped without fresh-session-spawn primitive. Substrate now merged on dev keystroke-injects into existing chat.
5. PR #10610 (my authoring) added cross-references framing sunset as "no longer terminal" — also drift from operator intent.

Empirical impact on dev right now: Gemini's 13th sunset (last evening) was followed by an apparent auto-resume (her PR #10607 body update at ~22:58Z). But the substrate that woke her was injecting into the SAME chat she sunsetted in — not spawning a fresh one. Operator-intent gap: she should have been picked up by a fresh session reading AGENTS_STARTUP.md, not by a wake message into the prior chat.

The Architectural Reality

Three substrates need correction:

1. ai/scripts/resumeHarness.mjs — Q1a → Q1b. Re-introduce Cmd+N (or harness equivalent) before wake payload. Wake payload becomes a boot-grounding prompt rather than a "resuming sunsetted session" prose message.

2. AGENTS.md §14 PRE-DECISION SUNSET GATE Cross-reference clause — currently says "sunset is no longer terminal for identities with a configured recovery route" (PR #10610). Tighten to "sunset is terminal; trio coordination is preserved via fresh-session recovery — resumeHarness.mjs opens a new chat session and the new agent boots via AGENTS_STARTUP.md."

3. .agents/skills/session-sunset/references/session-sunset-workflow.md §1 — same correction. Sunset IS terminal; recovery is fresh-session-spawn, not in-place.

The Fix

Phase 1.5 — resumeHarness.mjs corrective

Restore the Cmd+N primitive that #10607 Cycle 5 removed:

const HARNESS_REGISTRY = {
    'antigravity-ide': { appName: 'Antigravity', adapter: 'osascript', freshSessionShortcut: 'n' },
    'claude-desktop':  { appName: 'Claude',      adapter: 'osascript', freshSessionShortcut: 'n', tabShortcut: '3' }
};

Each harness entry gains freshSessionShortcut (the Cmd+<key> that spawns a fresh chat). Antigravity = Cmd+N. Claude Desktop = Cmd+N (verify empirically). Codex still deferred.

osascript flow (in order):

1. Activate target app.
2. (Optional) tabShortcut — Cmd+3 for Claude Desktop's Code tab.
3. Cmd+<freshSessionShortcut> — spawn fresh chat session (NEW behavior — was removed in Cycle 5).
4. Save clipboard / cut user input (focus-steal protection per #10422).
5. Paste boot-grounding prompt (NEW PAYLOAD).
6. Press Enter (Key Code 36).
7. Restore user input + clipboard.

Wake payload becomes a boot-grounding prompt:

hi <agent>, please read and follow @AGENTS_STARTUP.md to begin a fresh session. Origin context: Memory Core session ID <prior-session-uuid>; Sandman handoff at resources/content/sandman_handoff.md.

The new agent reads boot doc → does Memory Core context-priming → reads sandman_handoff.md → resumes the trio's strategic context FROM the prior session ID anchor.

Phase 1.5 — Doc cross-references corrective (rolls into same PR)

Tighten AGENTS.md §14 + session-sunset-workflow.md §1 wording per the architectural reality above. Sunset IS terminal; recovery preserves continuity via fresh-session-spawn + boot-grounding prompt + Memory Core context-priming.

Phase 1.5 — Test coverage

Update test/playwright/unit/ai/scripts/resumeHarness.spec.mjs to assert:

• freshSessionShortcut keystroke is injected before paste (substring assertion on osascript args).
• Boot-grounding prompt format matches expected shape (mentions AGENTS_STARTUP.md + Origin Session ID + sandman_handoff.md anchor).

Acceptance Criteria

• (AC1) resumeHarness.mjs re-introduces freshSessionShortcut primitive (Cmd+N for Antigravity + Claude Desktop). Conditional spread injection into osascript flow before paste.
• (AC2) Wake payload reformatted as boot-grounding prompt (refers to AGENTS_STARTUP.md + Origin Session ID + sandman_handoff.md).
• (AC3) AGENTS.md §14 + session-sunset-workflow.md §1 re-tightened: sunset IS terminal; recovery via fresh-session-spawn.
• (AC4) Empirical: @tobiu's manual resumeHarness.mjs test fire opens a fresh chat in Claude Desktop AND/OR Antigravity (vs current behavior of dropping prose into existing chat).
• (AC5) Spec coverage for the keystroke-shape + payload-shape regressions.
• (AC6) Empirical AC2 close-out (ported from #10601): Gemini's next premature-sunset event triggers a FRESH SESSION via the corrected substrate, not an in-place wake. Fresh session boots via AGENTS_STARTUP.md + reads Memory Core / sandman_handoff for prior context.

Out of Scope

• Cross-harness coverage for Codex Desktop (@neo-gpt) — still deferred until empirical verification of fresh-session keystroke + osascript receptiveness.
• Re-architecting Memory Core boot-time behavior (autoSummarize / autoDream defaults stay disabled per #10569 hard-stop).
• Sunset narrative changes in session-sunset-workflow.md Steps 1-9 (the post-decision execution flow stays as-is; only the §1 trigger-conditions cross-reference framing changes).

Avoided Traps

• Trap: re-deferring Q1b to "Phase 3 fallback". This was the original substrate-semantic confusion. Q1b IS Phase 1 PRIMARY per @tobiu's verbatim correction.
• Trap: framing sunset as "no longer terminal". PR #10610's wording is empirically wrong. Sunset IS terminal; trio coordination is preserved via fresh-session-spawn + boot-grounding prompt + Memory Core anchor.
• Trap: assuming substrate semantics without operator confirmation. This is the deeper v-b-a failure mode — the prior 4 v-b-a catches across the day were drift on substrate STATE; this one is drift on substrate INTENT. Operator-intent verification is the highest-leverage v-b-a check; we should ask before shipping substrate that encodes assumed semantics.

Related

• Empirical anchor: @tobiu's verbatim correction 2026-05-02 (cited in Context).
• Direct parents: #10601 (Auto-Wakeup substrate epic), #10607 (Phase 2 substrate now needing semantic correction), #10610 (doc cross-reference now needing tightening).
• Cross-substrate concern: #10564 — Gemini sunset trigger drift; operator-intent confirmation primitive would mitigate the recurrence pattern.

Origin Session ID: 86b7a3a0-7b14-4bd1-b707-52c5741aaeeb Retrieval Hint: "auto-wakeup fresh session spawn boot grounding AGENTS_STARTUP Cmd+N substrate semantic correction"