fix(pause): TaskStop guarantee tier for teammate shutdown + termination-primitive docs (v4.6.1) (#1161)

michael-wojcik · web-flow · commit 485046d1d0fd · 2026-07-12T10:10:49.000-04:00
* fix(pause): add TaskStop guarantee tier to teammate shutdown; codify TaskStop as the termination primitive

shutdown_request is cooperative-only — empirically, on the tmux backend an
approved shutdown_response does not terminate the teammate's pane/process.
pause.md step 6 now mirrors refresh.md step 5's two-tier shape (graceful
request, then TaskStop as the guarantee tier); the agent-teams skill and
orchestrator persona codify the same correction with one shared sentence
skeleton across all three surfaces. imPACT.md assessed: already
TaskStop-routed, no change.

* chore: bump plugin version to 4.6.1 (PATCH)

* fix(imPACT): shutdown_request is cooperative-only, not a standalone termination path

Rewrites the when-to-terminate clause to the shared cooperative-only /
termination-primitive skeleton, reconciles the 'last resort' framing with
the routine guarantee-tier role, and unifies the TaskStop signature to the
name form.

* fix(shutdown-docs): review-minors batch — honest dual-mode scoping, loop-error guidance, ported guards

refresh.md rationale aligned to the cooperative-only skeleton; pause.md
gains continue-on-not-found loop guidance plus refresh's no-sync-confirmation
and post-stop-send guards; SKILL.md scopes the non-termination claim to the
tmux backend (in-process semantics unprobed) and reframes memory-saving as
incremental; stagger phrasing unified (1 teammate/turn, request+stop = 2 ops).

* test: structural pins for pause two-tier shutdown + cross-surface termination skeleton

TestPauseShutdownStructure pins the two-tier loop invariants (order,
cooperative-only rationale, post-state note, no-delete line, error
idempotency); TestShutdownTerminationSkeletonAcrossSurfaces asserts the
uniform cooperative-only skeleton on all four shutdown surfaces so a
single-surface regression desyncs loudly.

* test: add imPACT.md to the termination-skeleton surface pins

* fix(teammate_idle): two-tier the force-threshold shutdown advisory

The ACTION-REQUIRED message the hook emits for the orchestrator now
instructs the graceful request followed by TaskStop, with the
cooperative-only rationale; test pins both tokens.
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
       "name": "PACT",
       "source": "./pact-plugin",
       "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
-      "version": "4.6.0",
+      "version": "4.6.1",
       "author": {
         "name": "Synaptic-Labs-AI"
       },
diff --git a/README.md b/README.md
@@ -605,7 +605,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-plugin/
 │           └── PACT/
-│               └── 4.6.0/       # Plugin version
+│               └── 4.6.1/       # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/
diff --git a/pact-plugin/.claude-plugin/plugin.json b/pact-plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.6.0",
+  "version": "4.6.1",
   "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
   "author": {
     "name": "Synaptic-Labs-AI",
diff --git a/pact-plugin/README.md b/pact-plugin/README.md
@@ -1,6 +1,6 @@
 # PACT — Orchestration Harness for Claude Code
 
-> **Version**: 4.6.0
+> **Version**: 4.6.1
 
 Turn a single Claude Code session into a managed team of specialist AI agents that prepare, design, build, and test your code systematically.
 
diff --git a/pact-plugin/agents/pact-orchestrator.md b/pact-plugin/agents/pact-orchestrator.md
@@ -407,6 +407,8 @@ Exceptions:
 - rePACT sub-scope specialists shut down after their nested cycle (orchestrator relays handoff details to subsequent sub-scopes)
 - comPACT specialists shut down when user chooses "Pause work for now"
 
+`shutdown_request` is cooperative-only — empirically, on the tmux backend an approved `shutdown_response` does not terminate the teammate's pane/process. `TaskStop("{teammate_name}")` is the authoritative termination primitive (reaps the pane/process and removes the roster entry; the team config file and team identity survive): any flow that requires a teammate actually gone MUST follow the graceful request with `TaskStop`.
+
 **Inter-teammate messages always go individually by name.** `SendMessage` requires a specific `to=` recipient — there is no broadcast addressing mode. To reach multiple teammates (HALT, shutdown, plan approval, structured protocol messages, plain-text announcements), iterate over the relevant teammates and send one `SendMessage` per recipient. Use the Lead-Side HALT Fan-Out idiom below as the canonical pattern.
 
 ### Lead-Side HALT Fan-Out
diff --git a/pact-plugin/commands/imPACT.md b/pact-plugin/commands/imPACT.md
@@ -117,7 +117,7 @@ Answer three questions:
 | **Redo prior phase** | Issue is upstream in P→A→C→T | Re-delegate to relevant agent(s) to redo the prior phase |
 | **Augment present phase** | Need help in current phase | Re-invoke blocked agent with additional context + parallel agents |
 | **Invoke rePACT** | Sub-task needs own P→A→C→T cycle | Use `/PACT:rePACT` for nested cycle |
-| **Terminate agent** | Agent unrecoverable (infinite loop, context exhaustion, stall after resume) | `TaskStop(task_id=taskId)` (force-stop: terminates immediately, non-cooperative) + `TaskUpdate(taskId, status="completed", metadata={"terminated": true, "reason": "..."})` |
+| **Terminate agent** | Agent unrecoverable (infinite loop, context exhaustion, stall after resume) | `TaskStop("{agent-name}")` (force-stop: terminates immediately, non-cooperative) + `TaskUpdate(taskId, status="completed", metadata={"terminated": true, "reason": "..."})` |
 | **Not truly blocked** | Neither question is "Yes" | Instruct agent to continue with clarified guidance |
 | **Escalate to user** | 3+ imPACT cycles without resolution | Proto-algedonic signal—systemic issue needs user input |
 
@@ -127,7 +127,7 @@ If the blocker reveals that a sub-task is more complex than expected and needs i
 /PACT:rePACT backend "implement the OAuth2 token refresh that's blocking us"
 ```
 
-**When to terminate**: Last resort — agent resumed once and stalled again, looping on same error 3+ times, context exhausted, or TeammateIdle stall unresolved by resume. `TaskStop` is a force-stop (immediate, non-cooperative); use `SendMessage(to="{agent-name}", message={"type": "shutdown_request"})` for cooperative shutdown. After termination, spawn a fresh agent with partial HANDOFF from the terminated agent's task metadata.
+**When to terminate**: Last resort — agent resumed once and stalled again, looping on same error 3+ times, context exhausted, or TeammateIdle stall unresolved by resume. `TaskStop` is a force-stop (immediate, non-cooperative) and the termination primitive; `SendMessage(to="{agent-name}", message={"type": "shutdown_request"})` is cooperative-only wind-down messaging that does not itself terminate the agent — any flow that requires the agent actually gone MUST follow the graceful request with `TaskStop`. "Last resort" scopes the decision to terminate an unrecoverable agent mid-workflow — not the `TaskStop` primitive itself, which is also the routine guarantee tier in graceful shutdown flows. After termination, spawn a fresh agent with partial HANDOFF from the terminated agent's task metadata.
 
 > **Force-termination is a carve-out** to the team-lead-only-completion rule. The `metadata.terminated == true` marker on the team-lead-driven `TaskUpdate(status="completed")` distinguishes this path from the standard cooperative acceptance flow. The terminated teammate is not idling on `awaiting_lead_completion`; the team-lead is force-completing an unrecoverable agent's task out-of-band. See [Completion Authority](../protocols/pact-completion-authority.md#completion-authority) for the carve-out table.
 
diff --git a/pact-plugin/commands/pause.md b/pact-plugin/commands/pause.md
@@ -105,14 +105,17 @@ The timestamp (`ts`) is set automatically by `make_event()` and serves the same
 
 ### 6. Shut Down Teammates
 
-Send `shutdown_request` individually to each active teammate **by name** and wait for responses. The secretary must have completed consolidation tasks (steps 1 and 3) before receiving the shutdown request.
+Shut down each active teammate **by name**, staggered 1 teammate per turn — the stagger counts ops, and request + stop = 2 ops (rate-limit discipline): graceful `shutdown_request` first, then `TaskStop("{teammate_name}")` as the guarantee tier — `shutdown_request` is cooperative-only (empirically, on the tmux backend an approved `shutdown_response` does not terminate the teammate's pane/process); `TaskStop` is authoritative. The secretary must have completed consolidation tasks (steps 1 and 3) before receiving the shutdown request.
 
 ```
 For each active teammate:
   SendMessage(to="{teammate_name}", message={"type": "shutdown_request", "reason": "Session paused"})
+  then: TaskStop("{teammate_name}")
 ```
 
-Do NOT delete the team — it will be garbage-collected or reused on resume.
+Treat a `TaskStop` not-found / already-exited error as already-stopped success and CONTINUE the loop — never abort mid-iteration; an abort strands later teammates unstopped.
+
+EXPECTED post-state: each stop removes that member's roster entry — the config FILE and the team IDENTITY survive; a lead-only roster is the correct post-pause state, not corruption. Do NOT add synchronous send-confirmation (message delivery lands asynchronously) — verify by a disk re-read of the team config, or simply proceed. A send to an already-stopped teammate fails hard with a no-agent-reachable error — this is EXPECTED post-stop behavior, not a diagnostic detour. Do NOT delete the team — it will be garbage-collected or reused on resume.
 
 ### 7. Report
 
diff --git a/pact-plugin/commands/refresh.md b/pact-plugin/commands/refresh.md
@@ -117,7 +117,7 @@ The timestamp (`ts`) is set automatically by the journal writer and becomes the
 
 ### 5. SHUTDOWN teammates
 
-Shut down each active teammate **by name**, staggered 1-2 sends per turn (rate-limit discipline): graceful `shutdown_request` first, then `TaskStop(name)` as the guarantee tier — a teammate may reject the request mid-task; `TaskStop` is authoritative.
+Shut down each active teammate **by name**, staggered 1 teammate per turn — the stagger counts ops, and request + stop = 2 ops (rate-limit discipline): graceful `shutdown_request` first, then `TaskStop(name)` as the guarantee tier — `shutdown_request` is cooperative-only (empirically, on the tmux backend an approved `shutdown_response` does not terminate the teammate's pane/process); `TaskStop` is authoritative.
 
 ```
 For each active teammate:
diff --git a/pact-plugin/hooks/teammate_idle.py b/pact-plugin/hooks/teammate_idle.py
@@ -338,7 +338,10 @@ def main():
                 # to send a shutdown_request via systemMessage.
                 messages.append(
                     f"ACTION REQUIRED: Send shutdown_request to '{teammate_name}' "
-                    f"via SendMessage(type=\"shutdown_request\", recipient=\"{teammate_name}\")."
+                    f"via SendMessage(type=\"shutdown_request\", recipient=\"{teammate_name}\"), "
+                    f"then TaskStop(\"{teammate_name}\") — shutdown_request is "
+                    f"cooperative-only and does not itself terminate the teammate; "
+                    f"TaskStop is the termination primitive."
                 )
 
             output = {"systemMessage": IDLE_PREAMBLE + " | ".join(messages)}
diff --git a/pact-plugin/skills/pact-agent-teams/SKILL.md b/pact-plugin/skills/pact-agent-teams/SKILL.md
@@ -520,7 +520,9 @@ When you receive a `shutdown_request`:
 | Idle, consultant with no active questions, or domain no longer relevant | Approve |
 | Mid-task, awaiting response, or remediation may need your input | Reject with reason |
 
-> **Save memory before approving**: If you haven't saved domain learnings to your agent memory yet, do so before approving — your process terminates on approval.
+> **Save learnings incrementally**: under guarantee-tier shutdown flows the lead may follow the graceful request with an immediate `TaskStop`, so you can be reaped before ever seeing the request. Save domain learnings to your agent memory as you work and treat any turn as possibly your last; approving a `shutdown_request` is a courtesy, not your save trigger.
+
+`shutdown_request` is cooperative-only. Empirically, on the tmux backend an approved `shutdown_response` does not terminate the teammate's pane/process — approval authorizes termination but does not perform it. On the in-process backend, `shutdown_response` semantics are unprobed: platform documentation claims approval terminates the process, but this is unverified in either direction. `TaskStop` is the termination primitive; any flow that requires a teammate actually gone MUST follow the graceful request with `TaskStop` (or verify pane/process death).
 
 ## Completion Integrity (SACROSANCT)
 
diff --git a/pact-plugin/tests/test_commands_structure.py b/pact-plugin/tests/test_commands_structure.py
@@ -1069,3 +1069,108 @@ def test_team_config_expectations_h1_h2(self, bootstrap_text):
         # H1 (ghost-detection)
         assert "do NOT blind-retry `Agent()`" in bootstrap_text
         assert "Check for inbound messages" in bootstrap_text
+
+
+# =============================================================================
+# pause.md teammate-shutdown structural pins + cross-surface termination
+# skeleton — deliberate drift detectors, anchored on stable tokens agreed
+# with the doc surfaces. Surrounding prose is intentionally unpinned.
+# =============================================================================
+
+
+class TestPauseShutdownStructure:
+    """Structural pins for commands/pause.md's teammate-shutdown step (LLM-loaded).
+
+    Each assertion is a drift detector: it anchors on a stable token and its
+    docstring names the regression it catches. Prose around the tokens is
+    deliberately unpinned so wording can evolve without touching these tests.
+    """
+
+    @pytest.fixture
+    def pause_text(self):
+        return (COMMANDS_DIR / "pause.md").read_text(encoding="utf-8")
+
+    def test_taskstop_guarantee_tier_present(self, pause_text):
+        """Detects: silent regression to single-tier shutdown. Dropping the
+        TaskStop line from the per-teammate loop reverts pause to the
+        cooperative-only request, which does not by itself terminate the
+        teammate's pane/process — panes would survive every pause."""
+        assert 'then: TaskStop("{teammate_name}")' in pause_text
+
+    def test_graceful_request_precedes_taskstop(self, pause_text):
+        """Detects: tier inversion. TaskStop issued before the graceful
+        shutdown_request reaps teammates before they can save agent memory
+        and approve — the cooperative tier must come first. Both anchor
+        literals occur exactly once in pause.md, so first-occurrence
+        index comparison encodes the loop ordering."""
+        request = pause_text.index('"type": "shutdown_request"')
+        stop = pause_text.index('then: TaskStop("{teammate_name}")')
+        assert request < stop
+
+    def test_cooperative_only_rationale_present(self, pause_text):
+        """Detects: loss of the rationale that makes the guarantee tier
+        non-optional. Without the cooperative-only statement, a future
+        editor can plausibly judge the TaskStop line redundant and remove
+        it as cleanup."""
+        assert "cooperative-only" in pause_text
+
+    def test_expected_post_state_note_present(self, pause_text):
+        """Detects: removal of the post-state expectation. A lead-only
+        roster after the stops is the correct post-pause state, not
+        corruption — losing this note invites 'repair' behavior (team
+        deletion or blind respawns) on resume."""
+        assert "EXPECTED post-state" in pause_text
+
+    def test_no_team_delete_invariant_survives(self, pause_text):
+        """Detects: the team-deletion prohibition being dropped while the
+        shutdown step is edited — the config file and team identity must
+        survive a pause for resume to reuse them."""
+        assert "Do NOT delete the team" in pause_text
+
+    def test_taskstop_error_idempotency_present(self, pause_text):
+        """Detects: loss of the already-stopped-success rule. Without it, a
+        TaskStop not-found / already-exited error mid-loop reads as a
+        failure and can abort the remaining teammate shutdowns instead of
+        continuing the loop."""
+        assert "already-stopped success" in pause_text
+
+
+# Per-surface stable anchors for the shutdown termination-primitive skeleton.
+# Every listed surface carries the uniform 'cooperative-only' statement
+# (refresh.md's rationale clause is harmonized to the shared skeleton
+# sentence); refresh.md additionally pins its two-tier loop/tier tokens as
+# secondary structural anchors. Presence-only assertions — occurrence counts
+# and surrounding prose are not pinned. Any LLM-loaded surface that instructs
+# or reasons about teammate shutdown qualifies for a row here.
+TERMINATION_SKELETON_SURFACES = [
+    ("commands/pause.md", ("cooperative-only",)),
+    ("commands/refresh.md", ("cooperative-only", "then: TaskStop", "guarantee tier")),
+    ("commands/imPACT.md", ("cooperative-only",)),
+    ("skills/pact-agent-teams/SKILL.md", ("cooperative-only",)),
+    ("agents/pact-orchestrator.md", ("cooperative-only",)),
+]
+
+
+class TestShutdownTerminationSkeletonAcrossSurfaces:
+    """The shutdown termination rule spans multiple LLM-loaded surfaces.
+
+    Detects: single-surface drift. An edit that removes the rule from one
+    surface while the others keep it silently forks the team's understanding
+    of whether shutdown_request alone terminates a teammate (it does not —
+    TaskStop is the termination primitive).
+    """
+
+    @pytest.mark.parametrize(
+        ("relpath", "tokens"),
+        TERMINATION_SKELETON_SURFACES,
+        ids=[relpath for relpath, _ in TERMINATION_SKELETON_SURFACES],
+    )
+    def test_surface_carries_termination_skeleton(self, relpath, tokens):
+        text = (COMMANDS_DIR.parent / relpath).read_text(encoding="utf-8")
+        for token in tokens:
+            assert token in text, (
+                f"{relpath} lost the shutdown termination-skeleton anchor "
+                f"{token!r}. Every surface that instructs teammate shutdown "
+                f"must state (or embody) the two-tier rule: shutdown_request "
+                f"is cooperative-only; TaskStop is the termination primitive."
+            )
diff --git a/pact-plugin/tests/test_teammate_idle.py b/pact-plugin/tests/test_teammate_idle.py
@@ -600,3 +600,6 @@ def test_shutdown_message_includes_action_required(self, capsys, tmp_path):
         msg = output.get("systemMessage", "")
         assert "ACTION REQUIRED" in msg
         assert "shutdown_request" in msg
+        # Two-tier pin: the advisory must carry the cooperative-only rationale AND the TaskStop tier (request-only guidance = regression).
+        assert "cooperative-only" in msg
+        assert "TaskStop" in msg

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "PACT",`
`3`		`- "version": "4.6.0",`
	`3`	`+ "version": "4.6.1",`
`4`	`4`	`"description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Synaptic-Labs-AI",`