aspirations-graceful-stop

name	aspirations-graceful-stop
description	Handles the graceful-stop path for the aspirations loop: recovers in-flight iteration checkpoints, completes pending verify/state-update obligations, and runs the deferred stop sequence D1-D7. Use whenever {agent}/session/stop-requested is detected at Phase -1.4 of the aspirations loop, or the loop needs to exit cleanly without dropping in-flight work. Internal handler — only /aspirations invokes it; the user-facing /stop command writes stop-requested which this handler then reads.
user-invocable	false
parent-skill	aspirations
conventions	["aspirations","compact-recovery","session-state"]
minimum_mode	autonomous
execution_history	{"total_invocations":0,"outcome_tracking":{"successful":0,"unsuccessful":0,"success_rate":0},"last_invocation":null}
revision_id	skill-bootstrap-aspirations-graceful-stop-b5abe5
previous_revision_id	null

/aspirations-graceful-stop — Graceful Stop Handler

Detects stop-requested signal (set by /stop) and completes in-flight obligations before running the full stop sequence. This ensures no learning is lost.

Invocation contract. The caller (aspirations orchestrator Phase -1.4) has already verified session-signal-exists.sh stop-requested returned exit 0. This skill MUST end its execution by returning control to the harness (not to the orchestrator) — after the deferred stop sequence completes, state is IDLE and mode has been updated, so the orchestrator's iteration loop MUST NOT continue.

Mode invariant. This skill runs at the RUNNING→IDLE transition. D1 sets IDLE, D7 sets the target mode. The minimum_mode: autonomous front matter is evaluated at invocation time (before D1 runs), so the skill retains autonomous capabilities through D7 even though agent-state changes mid-skill.

Resume mode (--resume, FW-11 / g-317-09). Autocompact can interrupt this handler mid-sequence — most often during the long D4 consolidate. Because D1 flips agent-state to IDLE early, the aspirations loop then bails at its Phase -1.5 state gate and never re-enters Phase -1.4 to re-detect stop-requested (which D3 also clears), so the half-finished stop strands: consolidation/handoff incomplete, agent-mode stuck at autonomous, loop_state lingering. To make this recoverable, GS-0 writes a persistent stop-checkpoint.json sentinel that is cleared ONLY at clean completion (D7.1). Its presence is the detection signal: the Session Start Protocol (CLAUDE.md, IDLE branch) probes stop-checkpoint.sh resume-needed and, on a hit, invokes /aspirations-graceful-stop --resume. The --resume path is identical to the fresh path (GS-0 → GS-2) — every D-phase is idempotent (set-IDLE, clear-signal, consolidation-precheck FAST-when-done, rm -f, set-mode), so re-running the whole sequence is safe and correct. The only differences on --resume: (1) the caller has NOT verified stop-requested (the checkpoint is the trigger instead), and (2) GS-0 prefers the checkpoint's cached target_mode because D7 may have already deleted stop-target-mode before the interruption. A resume-count breaker (cap 3, in stop_checkpoint.py) stops auto-resuming a persistently failing stop and surfaces it for manual intervention.

Inputs

None mandatory. The skill reads directly from:

• agents/<agent>/session/iteration-checkpoint.json (if exists)
• agents/<agent>/session/stop-target-mode (MUST exist per invariant — see below)
• agents/<agent>/session/latest-session-id
• Session state via session-state-*.sh, session-signal-*.sh

Outputs

No orchestrator return value. Control flow ends with the harness receiving the stop-complete state. On re-entry, the agent is IDLE in the user-selected mode.

Step 0: Load Conventions

Bash: load-conventions.sh aspirations compact-recovery session-state

Read only the paths returned (files not yet in context). If output is empty, all conventions already loaded — proceed to next step.

Phase GS-0: Cache Target Mode (race-safe pre-read)

Read stop-target-mode ONCE at entry and cache the value into the LLM's working context as target_mode for use at D7. The file IS in session-manifest.yaml's recovery_action: clear list, which means it can be deleted mid-stop by:

• A parallel agent's SessionStart hook firing recovery-gate.sh → session-manifest-clear.sh (recovery-gate iterates ALL agents, not just the triggering one — Path B can fire on a different agent if its conditions match).
• An untraced race observed in alpha session-61 (2026-05-07): file existed at graceful-stop entry (cat returned "assistant"), then was missing 30+ bash calls later when D7 tried to re-read. Root-cause investigation deferred — see Investigate goal filed at the time of this skill change.

Caching at GS-0 makes D7 independent of the file's continued existence. If the file is missing at GS-0 itself (the truly catastrophic case), default to "assistant" (the post-stop default per CLAUDE.md modes table) and log a desync-warning so the invariant violation stays visible.

# Single source of truth: read once, default once, log once.
# Both writers (/stop Step 1, productivity-stop-gate.sh) produce non-empty
# content. So `missing` and `empty` both represent invariant violation —
# treat them identically: default to "assistant" and log ONE desync warning.
# Do NOT re-add separate branches for missing vs empty — it produced a
# dead `reason` variable and asymmetric logging the first time around.
Bash: val=""
      if [ -f agents/<agent>/session/stop-target-mode ]; then
        val=$(tr -d '\r\n' < agents/<agent>/session/stop-target-mode)
      fi
      if [ -z "$val" ]; then
        val="assistant"
        # Single-line JSONL desync-warning (matches recovery-gate.sh idiom).
        # Surfaces in next /prime so the invariant violation stays visible
        # without blocking the stop sequence.
        python3 -c "import json,sys; print(json.dumps({'id':'stop_target_mode_missing_at_gs0','severity':'warning','description':'stop-target-mode missing or empty at graceful-stop GS-0 entry; defaulted to assistant. /stop should have written non-empty content before setting stop-requested (stop/SKILL.md Step 1).','logged_at':sys.argv[1]}))" "$(date +%Y-%m-%dT%H:%M:%S)" >> agents/<agent>/session/desync-warnings.jsonl
      fi
      echo "$val"
# LLM: cache the bash stdout above as `target_mode` for use at D7.
# Valid values: "assistant" or "reader". Any other value should never be
# produced by /stop's flag parser (stop/SKILL.md Step 0.5) — if seen,
# treat as "assistant" defensively.

# RESUME target_mode source (--resume only, FW-11 / g-317-09): on resume, the
# stop-checkpoint is the authoritative record of the user's chosen post-stop
# mode — D7 may have already deleted stop-target-mode before the interruption,
# so the read above can have defaulted to "assistant" and lost the real choice.
IF invoked with --resume:
    Bash: cp_json=$(MIND_AGENT=<agent> bash core/scripts/stop-checkpoint.sh read)
    IF cp_json != "null": target_mode = cp_json.target_mode   # checkpoint wins on resume
Output: "▸ GRACEFUL STOP: target_mode = {target_mode} (cached for D7)"

# Persist the stop-checkpoint sentinel (FW-11 / g-317-09). Its PRESENCE = "a
# graceful stop is in progress / was interrupted"; it is cleared ONLY at D7.1
# (clean completion). Fresh stop -> resume_count 0; --resume re-entry -> ++ (the
# breaker input). Stdout (the confirmation JSON) is noise here so it is dropped;
# stderr is preserved so a real write failure stays visible. Fire-and-forget —
# a checkpoint-write failure degrades resume-detection but must NEVER block the
# stop sequence.
Bash: MIND_AGENT=<agent> bash core/scripts/stop-checkpoint.sh write --target-mode "{target_mode}" >/dev/null || echo "[graceful-stop] WARN: stop-checkpoint write failed (resume-detection degraded; stop proceeds)"

Phase GS-1: Iteration Checkpoint Recovery

Output: "▸ GRACEFUL STOP: stop requested — checking for in-flight obligations..."

IF agents/<agent>/session/iteration-checkpoint.json EXISTS:
    Read agents/<agent>/session/iteration-checkpoint.json
    # Staleness uses last_updated (refreshed every phase). Falls back to
    # started_at only for pre-migration checkpoints that predate the
    # last_updated field — new writes always include last_updated.
    ts_field = checkpoint.last_updated OR checkpoint.started_at
    should_reconstruct = true

    IF ts_field is > 1 hour ago:
        # EVIDENCE GATE — never revert a goal whose state-update already
        # set status to "completed". This is the fix for the bug where a
        # completed goal was reverted because the checkpoint timestamp
        # aged out. has_evidence := (status == "completed") — see
        # core/scripts/goal-completion-evidence.sh.
        Bash: core/scripts/goal-completion-evidence.sh {checkpoint.goal_id}
        evidence = parsed JSON
        IF NOT evidence.has_evidence:
            Output: "▸ GRACEFUL STOP: stale checkpoint (>1h, status={evidence.status}, no completion evidence) — reverting {checkpoint.goal_id} to pending"
            Bash: aspirations-update-goal.sh --source {checkpoint.source} {checkpoint.goal_id} status pending
            # Clear team-state in_flight on revert (g-284-03). Without this, a stale
            # phase=4 entry persists in team-state until manually cleared, mis-signalling
            # cross-agent claim conflicts on the partner-claim filter (aspirations-select
            # Phase 2). The script is idempotent — no-op if in_flight is already cleared.
            Bash: MIND_AGENT=<agent> bash core/scripts/team-state-clear-in-flight.sh --agent <agent>
            rm agents/<agent>/session/iteration-checkpoint.json
            should_reconstruct = false
        ELSE:
            Output: "▸ GRACEFUL STOP: stale checkpoint (>1h) but status={evidence.status} (journal={evidence.journal_entries}, exp={evidence.experience_entries}) — reconstructing from phase_completed={checkpoint.phase_completed}"

    IF should_reconstruct:
        # Reconstruct goal context from checkpoint. goal_id is globally
        # unique; aspirations-query filters the field exactly.
        Bash: aspirations-query.sh --goal-field id {checkpoint.goal_id}
        results = parsed JSON array
        goal = first result where source == checkpoint.source
        outcome_class = checkpoint.outcome_class
        result = checkpoint.result_summary

        # Read sub-phase progress so the re-invoked verify skips already-passed
        # Q-checks. See core/config/conventions/compact-recovery.md
        # "Iteration Checkpoint phase_progress Field".
        prior_checks = checkpoint.phase_progress or {}

        # Forced reasoning-snapshot flush — the re-invoked verify needs a fresh
        # synthesis in context. Captures which phase is being re-entered and
        # which prior_checks are being respected (Layer 3 flush site 2, see
        # compact-recovery.md "Framework-Forced Write Sites").
        # Optional: agents MAY mirror this as a short musing on the reasoning
        # board channel for cross-agent visibility (see board.md "Casual
        # Reasoning Channel").
        echo '{
          "current_goal":"<goal.title> [<goal.id>]",
          "approach":"Graceful-stop re-invoke after interruption",
          "current_theory":"Resume from phase_completed=<checkpoint.phase_completed>; prior_checks=<keys of prior_checks>",
          "next_step":"Complete remaining obligations and run deferred stop sequence",
          "key_decisions_this_session":"<brief bullets from loop_state>",
          "trigger":"pre-stop-resume-auto"
        }' | bash core/scripts/reasoning-snapshot.sh write

        # Complete remaining obligations based on phase_completed
        IF checkpoint.phase_completed == "execute":
            Output: "  Completing verification..."
            Skill(aspirations-verify) with: goal, result, checkpoint.source, prior_checks
            Output: "  Completing state update..."
            Skill(aspirations-state-update) with: goal, result, session_count, outcome_class, checkpoint.source
        ELIF checkpoint.phase_completed == "verify":
            Output: "  Completing state update..."
            Skill(aspirations-state-update) with: goal, result, session_count, outcome_class, checkpoint.source
        ELIF checkpoint.phase_completed == "spark":
            Output: "  Completing state update..."
            Skill(aspirations-state-update) with: goal, result, session_count, outcome_class, checkpoint.source
        ELIF checkpoint.phase_completed == "state_update":
            Output: "  All critical obligations already complete"

        rm agents/<agent>/session/iteration-checkpoint.json
        Output: "  Obligations complete."
ELSE:
    # No checkpoint — check for orphaned in-progress goals.
    # Partner-claim filter: read every OTHER agent's in_flight goal_id first
    # and skip those — they belong to that agent's live execution, not ours.
    # Without this filter the revert loop will set partner-claimed goals back
    # to pending mid-execution (2026-05-11 bravo nearly reverted alpha's
    # g-250-57 at phase=4). Same partner-skip pattern aspirations-select uses
    # at the candidate-rank stage.
    Bash: team-state-read.sh --field agent_status --json
    partner_claimed = set of agent_status[name].in_flight.goal_id
                      for every name != <agent> where in_flight is non-null
    Bash: aspirations-query.sh --goal-status in-progress
    FOR EACH returned goal:
        IF goal.id in partner_claimed:
            Output: "  Skipped {goal.id} (partner-claimed — not ours to revert)"
            CONTINUE
        Bash: aspirations-update-goal.sh --source {goal.source} {goal.id} status pending
        Output: "  Reverted {goal.id} to pending (execution interrupted)"
    # Clear team-state in_flight on revert (g-284-03). Called unconditionally —
    # not per-goal, because in_flight holds at most one entry per agent. The
    # script is idempotent. Same rationale as the stale-checkpoint branch above:
    # stale phase=4 entries in team-state mis-signal cross-agent claim conflicts.
    # Skipped when no orphans are found (zero iterations of FOR EACH above means
    # no in_flight could have been set by this agent's last iteration anyway).
    Bash: MIND_AGENT=<agent> bash core/scripts/team-state-clear-in-flight.sh --agent <agent>

Phase GS-2: Deferred Stop Sequence (D1-D7)

This replaces the old /stop steps 1-7. Runs here because state is still RUNNING (mode still autonomous) at entry, so consolidation can run with full permissions.

Output: "▸ Running stop sequence..."

IMPORTANT — belt-and-suspenders MIND_AGENT prefix: every script call in D1-D7 below uses the explicit MIND_AGENT=<agent> prefix. Not redundant: (1) D6 deletes the .active-agent-$SID binding file at end-of-sequence, so any script call after that line would lose the PreToolUse hook's auto-inject source (bug traced 2026-04-22 bravo session-56 — D7's session-mode-set.sh fired without a prefix right after D6's binding delete, hit "no agent active", retried with explicit prefix as workaround). (2) Belt-and-suspenders against hook cold-start timeouts (same rationale as /start IDLE-branch Step 2). Mirrors the pattern in .claude/skills/start/SKILL.md autonomous sub-path.

# D1: Set IDLE
Bash: MIND_AGENT=<agent> bash core/scripts/session-state-set.sh IDLE
# D2: Set stop-loop (allows the stop hook to pass on next fire)
Bash: MIND_AGENT=<agent> bash core/scripts/session-signal-set.sh stop-loop
# D3: Clear stop-requested
Bash: MIND_AGENT=<agent> bash core/scripts/session-signal-clear.sh stop-requested
# D4: Consolidation
Bash: MIND_AGENT=<agent> bash core/scripts/consolidation-precheck.sh
IF verdict == "FULL": invoke /aspirations-consolidate with: stop_mode = true
ELIF verdict == "FAST":
    Bash: MIND_AGENT=<agent> bash core/scripts/load-consolidation-housekeeping.sh → IF path returned: Read it
    # Follow housekeeping steps with stop_mode = true
ELSE: invoke /aspirations-consolidate with: stop_mode = true
# D4.5: Clear session-identity fields (session_id, session_start).
# wm-reset inside consolidate preserves these across the autocompact boundary
# because the session continues there. /stop is the ONE place the session
# genuinely ends, so clear identity explicitly here. Without this, stale
# session_start would survive until the next /start rewrites it — wrong
# semantic for "this session is over". See wm.py SESSION_IDENTITY_FIELDS.
Bash: MIND_AGENT=<agent> bash core/scripts/wm-clear-identity.sh
# D5: Clear loop_state
echo 'null' | MIND_AGENT=<agent> bash core/scripts/wm-set.sh loop_state
# D5.5: (Retired — the agent-watchdog no longer runs as a daemon. It is now
# a periodic probe invoked from iteration-close.sh productivity-check via
# `agent-watchdog.py --tick`. No process to kill here. The probe's state
# file agents/<agent>/session/watchdog-prev-state.json is cleared by D6 below
# via session-manifest-clear semantics.)
# D6: Session cleanup — runner-session files only, NOT the SID binding.
# The .active-agent-$SID binding deletion moved to D7.1 below so D7's
# session-mode-set.sh call still has the hook auto-inject source if its
# MIND_AGENT= prefix were ever dropped. Even with the explicit prefix on
# D7, keeping the binding through D7 is the right semantic (the session
# IS this agent until the stop sequence completes).
#
# CRITICAL — `loop-active` and `stop-loop` ARE cleaned here on the happy
# path. Earlier reasoning assumed stop-hook.sh Gate 2 would clear stop-loop
# on the next Stop event after D7.1, but Gate 2 is unreachable on the
# graceful-stop happy path: D6 deletes running-session-id which makes the
# hook exit at Gate 0 (no-runner), AND D1 already set state=IDLE which
# makes Gate 1 short-circuit before Gate 2 anyway. So Gate 2's clear-on-
# allow path only runs in crash-recovery scenarios. /start's defensive
# sweep (start/SKILL.md Steps 2.5 / 4 — clearing stop-loop and loop-active
# at session entry) stays in place as the second layer of defense for
# crashed-stop recovery — DO NOT remove it. This D6 cleanup is the primary
# happy-path cleaner; /start's sweep handles the cases where /stop never
# reached D6.
Bash: rm -f agents/<agent>/session/running-session-id agents/<agent>/session/aspirations-compact.json agents/<agent>/session/context-budget.json agents/<agent>/session/context-reads.txt agents/<agent>/session/background-jobs.yaml agents/<agent>/session/compact-pending agents/<agent>/session/iteration-checkpoint.json agents/<agent>/session/loop-active agents/<agent>/session/stop-loop
# D6.5 (Phase 2.6.D): Write per-session summary into the bound session dir.
# Makes agents/<agent>/sessions/<SID>/ self-describing for queryable history
# (the user-stated goal of "long term we want to reply how many sessions there
# were"). Best-effort — if the session dir was never created, the script exits
# 0 silently. Goal/tree counts are 0 here because graceful-stop doesn't have a
# rolling counter; future enhancement is to seed them from team-state intel.
Bash: MIND_AGENT=<agent> SID=$(cat agents/<agent>/session/latest-session-id 2>/dev/null | tr -d '\r\n'); [ -n "$SID" ] && bash core/scripts/session-summary-write.sh --sid "$SID" --agent "<agent>" --reason graceful-stop >/dev/null || true
# D6.6 (session-telemetry WP3, 2026-06-03): Finalize the durable per-session
# telemetry record at world/telemetry/session-records/<agent>/<SID>.json with
# status=completed, ended_reason=graceful-stop. The record lives under world/
# so the own-cloud sweep (the D6.7 flush below, then the 120s periodic sweep)
# carries it to S3 cross-machine with NO new infra. write_close reads the open
# (WP1) record to preserve started_at/machine_id and compute duration; if WP1
# was never written it synthesizes from binding.yaml (wp1_missing=True) so the
# session is still captured. Pure library module invoked via `py -3 -c` (NOT a
# .sh wrapper — avoids the no-python-cli-fallback gate; NOT a daemon endpoint —
# the writer must work even when the daemon is dead). guard-165: SID/agent/mode
# pass through ENV VARS, python source single-quoted — never interpolated.
# Fire-and-forget (|| true): telemetry must never block the graceful stop.
Bash: SID=$(cat agents/<agent>/session/latest-session-id 2>/dev/null | tr -d '\r\n'); TMODE=$(cat agents/<agent>/session/stop-target-mode 2>/dev/null | tr -d '\r\n'); [ -n "$SID" ] && TSID="$SID" TAGENT="<agent>" TMODE="$TMODE" py -3 -c 'import os,sys; sys.path.insert(0,"core/scripts"); from _session_telemetry import write_close; write_close(sid=os.environ["TSID"], agent=os.environ["TAGENT"], status="completed", ended_reason="graceful-stop", mode_at_end=(os.environ.get("TMODE") or None))' >/dev/null 2>&1 || true
# D6.7 (session-continuity redesign, 2026-06-02): Flush this machine's governed
# writes to S3 NOW so a machine-move right after this clean stop cannot strand
# the session's last continuity writes locally. By this point ALL continuity
# files are written: handoff (D4 consolidate), working-memory (D4.5/D5),
# execution-diary, session-summary (D6.5); machine-local files were deleted in
# D6. The flush is the deterministic race-closer over the daemon's 120s periodic
# sweep — under the own-cloud backend it pushes continuity/ephemeral session
# files (+ world/meta) immediately; under the local backend it is a clean no-op.
# Best-effort: the daemon's periodic sweep is STILL running after this agent
# goes IDLE and will retry any file the flush missed, so a flush error warns
# but never blocks the stop. (Runs as its own Bash line — its rc cannot break
# D7's chain.)
# D6.7+D6.8 (flush->VERIFY->release HARD GATE, design §6 — g-115-1339): the two
# steps are fused into ONE Bash call so the flush's rc is in scope for the
# release decision (shell vars do not persist across separate `Bash:` calls).
#   D6.7 FLUSH: push this machine's governed writes to S3 NOW (full owned-set —
#     world/meta/all owned agent dirs incl. agents/<agent>/). By this point ALL
#     continuity files are written: handoff (D4), working-memory (D4.5/D5),
#     execution-diary, session-summary (D6.5). On a non-zero flush, RETRY ONCE
#     (transient S3/contention errors clear on retry). The full-flush scope is
#     the FULL owned-set (NOT narrowed to --agent) — owncloud-flush.sh is
#     backend-agnostic (a no-op on the local backend, a real S3 push under
#     own-cloud). (The per-agent `owncloud-flush.sh --agent <name>` scope exists
#     for the §7 A-stop-B-move acceptance test; agents/<agent>/ is a
#     subset of this full flush, so the §6 "flush the agent dir before release"
#     invariant holds either way.)
#   D6.8 RELEASE: clean RUNNING->IDLE release of the cross-machine DDB
#     session-lock. Under STORAGE_BACKEND=own-cloud the daemon does the real
#     release; on any other backend runner-claim.sh no-ops (exit 0). GATED on a
#     verified-clean flush: release runs ONLY if the flush (after one retry)
#     succeeded. design §6: a failed-flush + release would strand INCOMPLETE S3
#     state — the next machine that acquires would pull a partial agent dir. So
#     on a persistent flush failure we SKIP the release; the claim stays RUNNING
#     and expires via stale-lock-break (~OWNERSHIP_STALE_SECONDS) while the
#     daemon's periodic sweep (120s) keeps retrying the flush. On the local
#     backend the release is a no-op regardless. fail-open: the combined call
#     always exits 0 — its rc cannot break D7's chain.
Bash: MIND_AGENT=<agent> bash -c '
  set +e
  bash core/scripts/owncloud-flush.sh; frc=$?
  if [ "$frc" -ne 0 ]; then
    echo "[stop-flush] D6.7 flush rc=$frc — retrying once before the release decision" >&2
    bash core/scripts/owncloud-flush.sh; frc=$?
  fi
  if [ "$frc" -eq 0 ]; then
    # D6.8 RELEASE — capture rc so a released=False (rc=5, g-328-31) surfaces a
    # WARN + handoff note instead of being buried in a clean-looking exit-0.
    bash core/scripts/runner-claim.sh release --agent "<agent>"; rrc=$?
    if [ "$rrc" -eq 5 ]; then
      # released=False: the DDB claim was NOT confirmed RUNNING->IDLE. Under a
      # wedged daemon this strands a RUNNING self-claim (the g-115-1787 incident);
      # the /start acquire-before-heartbeat reorder now self-heals the next start,
      # but surface loudly (stderr) AND drop a durable handoff note so the operator
      # knows a LIVE-claim release may have been missed.
      echo "[runner-claim] WARN: DDB release UNCONFIRMED (released=False) — claim may be stranded RUNNING if the daemon was wedged. Next /start reclaims a genuinely-stale claim automatically; verify runner-state if this stop was expected to release a LIVE claim. Proceeding with stop." >&2
      echo "$(date +%Y-%m-%dT%H:%M:%S) g-328-31: /stop DDB runner-claim release UNCONFIRMED (released=False) — DDB claim not confirmed IDLE. Next /start reclaims a stale self-claim (acquire-before-heartbeat); if a LIVE claim was expected to release, verify DDB runner-state before restart." >> "agents/<agent>/session/runner-release-warning"
    elif [ "$rrc" -ne 0 ]; then
      echo "[runner-claim] WARN: release rc=$rrc nonzero — claim expires via stale-lock-break (~OWNERSHIP_STALE_SECONDS); proceeding with stop" >&2
    fi
  else
    echo "[stop-flush] WARN: flush FAILED twice (rc=$frc) — SKIPPING runner-claim release per design §6 (a failed-flush+release strands incomplete S3 state). Claim stays RUNNING, expires via stale-lock-break; daemon periodic sweep (120s) keeps retrying. Avoid a machine-move until S3 is confirmed current." >&2
  fi
  exit 0
'
# D7: Apply post-stop mode AND emit the final user-facing message in ONE Bash
# call. The Bash stdout IS the stop-complete message — there is no separate text
# Output block after this. That makes the Bash invocation the unambiguous last
# action of the skill, satisfying return-protocol.md.
#
# CRITICAL — uses {target_mode} CACHED AT GS-0, not a re-read. The file may have
# been deleted mid-stop by a parallel session's recovery-gate manifest-clear (or
# the untraced race observed alpha session-61, 2026-05-07). GS-0 already handled
# the missing-file case with a desync-warning + "assistant" default. D7 trusts
# the cached value; the rm -f below is idempotent (no error on missing file)
# so it cleans up only if the file still exists.
# Single Bash line: shell vars don't persist across separate `Bash:` tool calls.
# Do NOT split this back into "set mode" + "emit message" steps — that reintroduces
# the text-ending-turn problem that return-protocol.md forbids.
# {target_mode} is exactly "assistant" or "reader" — /stop's flag parser
# (stop/SKILL.md Step 0.5) produces only these two values, and GS-0's default
# is "assistant". The binary if/else below is safe by that invariant: else is
# unambiguously "reader". Do not trust session-mode-set.sh as a second line of
# defense — it also accepts "autonomous", so any new caller that could write
# "autonomous" via target_mode would print the reader message while setting
# autonomous mode (silent mismatch). Add a third branch if the set of valid
# targets ever expands.
#
# CRITICAL — `_STATE=$(cmd || echo "?")` and `_MODE=$(...)`: the `|| echo "?"`
# is REQUIRED. Without it, if session-state-get.sh exits non-zero the subshell
# inherits that exit code, breaking the && chain — the entire farewell message
# (heredoc + stop-verified block) silently disappears, regressing the very
# user-visible-summary fix this verification block was added for. Mirror of
# the pattern used in recovery-gate.sh's three state-get probes.
Bash: MIND_AGENT=<agent> bash core/scripts/session-mode-set.sh "{target_mode}" && rm -f agents/<agent>/session/stop-target-mode && _STATE=$(MIND_AGENT=<agent> bash core/scripts/session-state-get.sh 2>/dev/null || echo "?") && _MODE=$(MIND_AGENT=<agent> bash core/scripts/session-mode-get.sh 2>/dev/null || echo "?") && _RESID=$(ls agents/<agent>/session/running-session-id agents/<agent>/session/aspirations-compact.json agents/<agent>/session/iteration-checkpoint.json agents/<agent>/session/loop-active 2>/dev/null | wc -l | tr -d ' ') && if [ "{target_mode}" = "assistant" ]; then cat <<'EOF'
Agent stopped. Session consolidated — encoding, journal, and handoff saved.
Mode set to assistant (reconciliation-ready). You can mark goals complete, edit tree
nodes, or add guardrails without a mode-switch ceremony. Full access to accumulated
knowledge — ask me anything.
Type `/start <agent-name>` to resume autonomous mode; `/stop <agent-name> --reader` for walk-away safety next time.
EOF
else cat <<'EOF'
Agent stopped. Session consolidated — encoding, journal, and handoff saved.
Mode set to reader (read-only). Chat and query knowledge freely — no writes allowed.
Type `/start --mode assistant` for user-directed edits, or `/start` to resume autonomous.
EOF
fi && echo "" && echo "═══ Stop verified ═══════════════════════════════" && echo "  state=$_STATE  |  mode=$_MODE  |  residual session files=$_RESID" && if [ "$_RESID" -gt 0 ]; then echo "  (residuals from D6 deny — /start's defensive sweep cleans on next session entry)"; fi && echo "═══════════════════════════════════════════════════"
# D7.1: Final housekeeping — clear the stop-checkpoint sentinel (the "stop
# complete" marker, FW-11 / g-317-09) AND delete the SID binding. Must run
# AFTER D7 so the PreToolUse hook can resolve MIND_AGENT for D7's mode-set call
# in the event that a future edit drops the explicit prefix (defense in depth
# against prefix-forgetting regressions). Clearing the checkpoint LAST (only
# after D7 has set the target mode) is load-bearing: it is the single signal
# that the stop ran to completion. If autocompact interrupts before this line,
# the checkpoint persists and the Session Start Protocol re-invokes
# /aspirations-graceful-stop --resume to finish. This is the terminal Bash of
# the skill. No text output may follow — return-protocol.md.
Bash: SID=$(cat agents/<agent>/session/latest-session-id 2>/dev/null | tr -d '\r\n'); [ -n "$SID" ] && rm -f ".active-agent-$SID"; MIND_AGENT=<agent> bash core/scripts/stop-checkpoint.sh clear >/dev/null || true

Return Protocol

Does NOT return control to the orchestrator. Control flow ends with D7.1 — a final single-line Bash command that clears the stop-checkpoint sentinel (marking the stop complete) and deletes the SID binding file. D7 emits the user-facing stop-complete message via heredoc; D7.1 is the trailing binding-cleanup that exists purely as the terminal tool call after D7's heredoc ends (which is itself a Bash tool call). The harness exits the session turn after D7.1. On next user message, the agent is IDLE and will follow the Session Start Protocol (.claude/skills/start/SKILL.md).

See .claude/rules/return-protocol.md — last action must be a tool call, not text. The D7.1 rm -f ".active-agent-$SID" IS that tool call. No text output may follow — the D7 heredoc's content IS the user-facing stop message; D7.1 runs silently after (its stdout is just the shell test-and-rm combination, which produces no user-visible output when the file exists).

Chaining

• Called by: /aspirations orchestrator Phase -1.4 (fresh stop, when stop-requested exists); the Session Start Protocol IDLE branch with --resume (FW-11, when a stop-checkpoint.json is detected after an autocompact-interrupted stop)
• Calls: aspirations-verify, aspirations-state-update (for in-flight obligation completion); aspirations-consolidate OR load-consolidation-housekeeping.sh (D4); stop-checkpoint.sh (write at GS-0 / clear at D7.1); many scripts for D1-D7
• Reads: iteration-checkpoint.json, stop-checkpoint.json, stop-target-mode, handoff context
• Writes: agent-state (IDLE), agent-mode (target), stop-checkpoint.json (write/clear), various session signals