Synaptic-Labs-AI
diff --git a/‎.claude-plugin/marketplace.json‎
Lines changed: 1 addition & 1 deletion b/‎.claude-plugin/marketplace.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎README.md‎
Lines changed: 1 addition & 1 deletion b/‎README.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎pact-plugin/.claude-plugin/plugin.json‎
Lines changed: 2 additions & 1 deletion b/‎pact-plugin/.claude-plugin/plugin.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎pact-plugin/README.md‎
Lines changed: 1 addition & 1 deletion b/‎pact-plugin/README.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎pact-plugin/commands/bootstrap.md‎
Lines changed: 16 additions & 1 deletion b/‎pact-plugin/commands/bootstrap.md‎
Lines changed: 16 additions & 1 deletion
diff --git a/‎pact-plugin/commands/refresh.md‎
Lines changed: 149 additions & 0 deletions b/‎pact-plugin/commands/refresh.md‎
Lines changed: 149 additions & 0 deletions
diff --git a/‎pact-plugin/hooks/refresh/__init__.py‎
Lines changed: 0 additions & 89 deletions b/‎pact-plugin/hooks/refresh/__init__.py‎
Lines changed: 0 additions & 89 deletions
@@ -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.5.8",
+      "version": "4.6.0",
       "author": {
         "name": "Synaptic-Labs-AI"
       },
 
@@ -605,7 +605,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-plugin/
 │           └── PACT/
-│               └── 4.5.8/       # Plugin version
+│               └── 4.6.0/       # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/
 
@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.5.8",
+  "version": "4.6.0",
   "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
   "author": {
     "name": "Synaptic-Labs-AI",
@@ -34,6 +34,7 @@
     "./commands/plan-mode.md",
     "./commands/wrap-up.md",
     "./commands/pause.md",
+    "./commands/refresh.md",
     "./commands/pin-memory.md",
     "./commands/telegram-setup.md",
     "./commands/prune-memory.md"
 
@@ -1,6 +1,6 @@
 # PACT — Orchestration Harness for Claude Code
 
-> **Version**: 4.5.8
+> **Version**: 4.6.0
 
 Turn a single Claude Code session into a managed team of specialist AI agents that prepare, design, build, and test your code systematically.
 
 
@@ -14,6 +14,8 @@ Read `team_name` from the **Current Session** block in the project's `CLAUDE.md`
 
 The platform manages exactly one team per session, named `{team_name}` — it is provisioned automatically; you do not create it (the `TeamCreate`/`TeamDelete` tools no longer exist). Use `{team_name}` for every specialist dispatch.
 
+**Team-config expectations (bidirectional)**: on resume, a PRESENT team config is reused — never re-create it. An ABSENT config is the NORM after a clean session end — the platform provisions the session team; both states are normal, neither is corruption. **Ghost-detection**: if a spawn or send fails with a team-not-found error, do NOT blind-retry `Agent()` — the platform spawn is non-atomic and the process may already be running. Check for inbound messages from the "failed" agent name first; re-spawn only if it stays silent.
+
 ## Step 2 — Spawn `pact-secretary`
 
 Spawn the session secretary using single-task dispatch — the `pact-secretary` agentType is exempt from the teachback gate. No Task A teachback round-trip.
@@ -25,12 +27,25 @@ Spawn the session secretary using single-task dispatch — the `pact-secretary`
 
 The secretary delivers the session briefing at spawn, answers memory queries during the session, and processes HANDOFFs at workflow boundaries. The briefing task is a discrete deliverable: the secretary MUST self-complete it (`TaskUpdate(status="completed")`) as the final act of delivering the briefing — you do NOT complete it, and you MUST NOT expect to. Completing the task does NOT end the secretary's role; it continues as memory consultant and HANDOFF harvester for the rest of the session. Memory queries from any other agent are blocked until the secretary is alive.
 
-Spawn the secretary **only once per session** — reuse the same secretary for any subsequent memory queries or HANDOFF harvesting.
+Spawn the secretary **only once per session** — reuse the same secretary for any subsequent memory queries or HANDOFF harvesting — AND respawn it after `/PACT:refresh`, whose shutdown stopped the previous secretary process. Post-refresh, respawning is MANDATORY BEFORE any SendMessage to the secretary name: a send to the stopped name resurrects its stale pre-refresh transcript instead of starting fresh.
 
 ## Step 3 — Surface paused state
 
 Paused state is surfaced **automatically** by the `session_init` hook: when the previous session ran `/PACT:pause`, it wrote a `session_paused` event to the session journal, and `session_init` reads that event on resume and injects the paused-work prompt into the SessionStart context. There is **no `paused-state.json` file** — do not attempt to read one (nothing writes it). Watch the SessionStart context for a "Paused work detected" line. If it appears, **do not silently resume.** Surface it to the user and ask whether to continue the paused workflow or start fresh; their choice drives next-step dispatch.
 
+**Refreshed state**: also watch the SessionStart context for a refreshed-workstream prompt (a "Refreshed workstream detected" line carrying a `refresh_ts=` key). If present, this is a DECLARED CONTINUATION, not a fresh start: surface the mid-flight state to the user (feature, next phase, worktrees, any HALT line) and AUTO-PROCEED to respawn the specialists the named next phase needs. Ask the user ONLY on inconsistency: the prompt's HALT line has no matching live blocker task in `TaskList` (or live blockers exist the prompt doesn't mention), a listed worktree path does not exist on disk, or the prompt's `team_name` (when present) does not match the `team_name` in the **Current Session** block. A HALT line always surfaces to the user regardless.
+
+**Consumption write (fire-once)**: immediately after confirming resumption (secretary respawned, mid-flight state surfaced), retire the refresh prompt by writing the consumption event — substitute the `refresh_ts=` value copied VERBATIM from the surfaced prompt:
+
+```bash
+python3 "{plugin_root}/hooks/shared/session_journal.py" write \
+  --type session_refresh_consumed --session-dir '{session_dir}' --stdin <<'JSON'
+{"refresh_ts": "{refresh_ts}"}
+JSON
+```
+
+If the prompt said `refresh_ts=UNAVAILABLE`, skip the write (the prompt may re-surface once; its staleness downgrade bounds the repetition). Never write a consumption event when no refresh prompt surfaced. On a quit-then-new-session resume the consumption event lands in the NEW session's journal (a harmless orphan record) — fire-once on that path is enforced by the one-hop-back journal read, while the ts-bound consumption covers the same-session paths (`/compact` and same-session `--resume`).
+
 ## Step 4 — Plugin banner
 
 Surface the plugin banner — a single line of the form `PACT plugin: <version> (root: ~/.claude/plugins/cache/pact-marketplace/PACT/<version>)` — in the bootstrap-confirmation reply. The banner is pre-rendered by the `format_plugin_banner()` helper in `hooks/shared/plugin_manifest.py` (reading the live version from `plugin.json`) and delivered through the `session_init` SessionStart system reminder + the per-prompt `peer_inject` surface; no manual composition is needed — echo what the hook already produced. If the session-start system reminder has been dropped (post-compaction), fall back in order: (a) read the `- Plugin root:` line in CLAUDE.md's Current Session block (the path embeds the version), then (b) read `plugin.json["version"]` directly. The `<version>` placeholder above is illustrative — do not substitute it manually.
 
@@ -0,0 +1,149 @@
+---
+description: Mid-workstream context checkpoint — harvest, persist, shut down teammates, stand by for /compact + /PACT:bootstrap
+---
+# PACT Refresh Protocol
+
+Reset the context window mid-workstream without losing state. Refresh harvests pending knowledge, persists a resumable checkpoint to the session journal, shuts down teammates, and stands by for the user to run `/compact` (canonical) and then `/PACT:bootstrap`. The workstream CONTINUES after the reset — nothing is closed, merged, or cleaned up.
+
+> **Cross-reference**: For a PR-open pause with later resumption, see [pause.md](pause.md). For end-of-session cleanup and close, see [wrap-up.md](wrap-up.md).
+
+---
+
+## When to Use / When NOT
+
+| Command | Purpose | Workstream state after |
+|---------|---------|------------------------|
+| `/PACT:pause` | PR open, resume the review later | Paused (PR open) |
+| `/PACT:wrap-up` | End-of-session cleanup + close | Ended |
+| `/PACT:refresh` | Mid-workstream context checkpoint | **Active — continues after `/compact` + `/PACT:bootstrap`** |
+
+Use refresh when the context window is near exhaustion while work is still mid-flight — for example CODE complete but TEST pending, a live HALT/algedonic signal, or worktrees holding unmerged commits. No orchestration retrospective runs (the arc is mid-flight, not ending); `/PACT:pin-memory` is optional; the harvest and its drain confirmation are MANDATORY.
+
+---
+
+## Constraints (apply to every step)
+
+- **LEAD-FRAME-ONLY**: every step that spawns, stops, or messages teammates runs in the lead frame. The team roster is flat — teammates cannot spawn or stop teammates.
+- **Never clean worktrees, branches, or commits.** Verification is read-only; the workstream continues after the reset.
+- **Never complete or delete tasks** — the feature task, phase tasks, and any HALT/algedonic signal tasks must survive for resume.
+- **Never write under `~/.claude/pact-refresh/`.** That directory is legacy state from a removed subsystem; checkpoint state lives ONLY in the session journal.
+
+---
+
+## Steps
+
+> **CRITICAL ordering**: HARVEST (step 2) MUST be drain-confirmed complete BEFORE the shutdown (step 5). The secretary must be alive to process HANDOFFs.
+
+### 1. Preflight — degenerate case
+
+Scan `TaskList` for an in_progress feature task. If NONE exists, tell the user refresh will proceed as harvest-only and `/PACT:wrap-up` may fit better; on their confirm, CONTINUE. Once proceeding, the journal write in step 4 is unconditional — the degenerate case writes a minimal event carrying the two required fields only.
+
+### 2. HARVEST — memory consolidation (Pass 2)
+
+```
+TaskCreate(subject="secretary: session consolidation (Pass 2)",
+  description="Run Consolidation Harvest for team {team_name}. Follow the Consolidation Harvest workflow in your pact-handoff-harvest skill. Report summary when done.")
+TaskUpdate(taskId, owner="secretary")
+```
+
+**Drain-confirmation gate (MUST)**: before ANY shutdown step, verify the consolidation task's status is `completed` by READING the task (`TaskGet`, or the raw task JSON on disk) — an explicit completion check, not ordering prose. Not completed ⇒ wait or nudge the secretary; do not proceed to step 5.
+
+### 3. PERSIST/VERIFY — read-only state check + payload computation
+
+For each active worktree, run `git status --porcelain` and report any uncommitted changes to the user — never clean, never commit on their behalf.
+
+Then compute the checkpoint payload:
+
+- `halt_active` + `halt_task_ids`: scan `TaskList` for tasks with `metadata.type` in {`blocker`, `algedonic`} and status not `completed`. Always computable — `false` and omit the ids when none are live.
+- `feature_task_id` / `feature_subject`: from the in_progress feature task (omit both in the degenerate case).
+- `team_name`: the active session team's name — the same value bootstrap reads from the Current Session block at resume, giving it an identity cross-check.
+- `next_phase`: from the phase-task state. Bounded vocabulary, writer-enforced (the journal validator does not check enums): `prepare|architect|code|test|peer-review|deploy`.
+- `worktrees`: JSON list of ABSOLUTE paths of the active worktrees.
+- `pr_number`: only when a PR is open — informational surface data; it never gates anything.
+
+### 4. Write the checkpoint to the session journal
+
+Emit `session_consolidated` only when step 2's consolidation actually completed, then write the `session_refreshed` checkpoint. The flag is **shell-clamped** via a three-branch `case`: `true` emits, `false` is a no-op, anything else fails fast as a template-substitution bug. Pass the literal string `true` or `false` for `{true_or_false}`.
+
+```bash
+set -e
+trap 'rc=$?; echo "[JOURNAL WRITE FAILED] refresh.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+case '{true_or_false}' in
+  true)
+    python3 "{plugin_root}/hooks/shared/session_journal.py" write \
+      --type session_consolidated --session-dir '{session_dir}' --stdin <<'JSON'
+{"pass": 2, "task_count": {task_count}, "memories_saved": {memories_saved}}
+JSON
+    ;;
+  false)
+    ;;  # intentional no-op
+  *)
+    echo "[refresh.md] invalid {true_or_false} flag: '{true_or_false}' (expected literal 'true' or 'false')" >&2
+    exit 1
+    ;;
+esac
+python3 "{plugin_root}/hooks/shared/session_journal.py" write \
+  --type session_refreshed --session-dir '{session_dir}' --stdin <<'JSON'
+{"consolidation_completed": {true_or_false}, "halt_active": {halt_active}, "halt_task_ids": {halt_task_ids}, "feature_task_id": "{feature_task_id}", "feature_subject": "{feature_subject}", "team_name": "{team_name}", "next_phase": "{next_phase}", "worktrees": {worktrees}, "pr_number": {pr_number}}
+JSON
+```
+
+**Degenerate case** (no active workstream): omit every optional field — write the two required fields only:
+
+```bash
+python3 "{plugin_root}/hooks/shared/session_journal.py" write \
+  --type session_refreshed --session-dir '{session_dir}' --stdin <<'JSON'
+{"consolidation_completed": {true_or_false}, "halt_active": false}
+JSON
+```
+
+> ⚠️ **Heredoc-stdin contract**: the writes use `--stdin <<'JSON' ... JSON` (quoted delimiter), so an apostrophe in a substituted value cannot close the shell quote and silently drop the event. The orchestrator must still produce JSON-valid string content (escape `\"`, `\\`, and control chars).
+
+**Event fields**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `consolidation_completed` | boolean | yes | Whether the step 2 harvest completed |
+| `halt_active` | boolean | yes | Whether any HALT/algedonic signal task is live at refresh time |
+| `halt_task_ids` | list of strings | no | Ids of the live signal tasks (diagnostic — the live task store is the SSOT at resume) |
+| `feature_task_id` | string | no | The in_progress feature task id |
+| `feature_subject` | string | no | The in_progress feature task subject |
+| `team_name` | string | no | The active session team's name — resume-time identity cross-check |
+| `next_phase` | string | no | Bounded vocabulary above |
+| `worktrees` | list of strings | no | Absolute paths of active worktrees |
+| `pr_number` | integer | no | Open PR number — surface-only, never gates surfacing |
+
+The timestamp (`ts`) is set automatically by the journal writer and becomes the checkpoint's claim id — bootstrap's consumption write binds to it.
+
+### 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.
+
+```
+For each active teammate:
+  SendMessage(to="{teammate_name}", message={"type": "shutdown_request", "reason": "Context refresh — checkpoint written, resuming after /compact"})
+  then: TaskStop("{teammate_name}")
+```
+
+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-refresh 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. Do NOT delete the team.
+
+### 6. STANDBY
+
+Report to the user:
+
+```
+"Context checkpoint complete. Run /compact now, then /PACT:bootstrap to resume mid-flight."
+```
+
+Until bootstrap runs:
+
+- **FORBID new dispatches** — no TaskCreate-and-assign, no specialist spawns.
+- **RESPAWN-BEFORE-SEND**: messaging ANY pre-refresh teammate name resurrects its stale transcript and re-adds the member — bootstrap must respawn a fresh process under that name first. This includes the secretary.
+- **Expect and IGNORE stragglers**: messages a teammate generated BEFORE its stop can deliver minutes later during standby. A straggler is NOT evidence the teammate survived; do not reply and do not re-engage — any reply triggers the resume-on-send hazard above.
+- `/clear` is tolerated but non-canonical (no compact summary is written; the bootstrap gate re-engages either way); `/compact` is the canonical path.
+
+If the Telegram bridge is active, send a notification:
+
+```
+telegram_notify("Context checkpoint complete. Run /compact, then /PACT:bootstrap to resume mid-flight.")
+```