wogiflow 2.21.0 → 2.22.1

package/.claude/commands/wogi-finalize.md

@@ -79,6 +79,79 @@ Pre-finalization checks:
 
 If checks fail, display warnings and suggest fixes before proceeding.
 
+### Step 2.5: Merge-Plan Gate (when `mergePlan.threshold` exceeded)
+
+**Activates when** the branch carries more commits than `config.finalization.mergePlan.threshold` (default **5**) OR the diff is flagged cross-repo by the workspace manifest. The gate writes — and requires the AI to fill in — `.workflow/scratch/merge-plan.md`. The gate exists because the "1-2h mostly mechanical" audit that predicted a 27-conflict merge (wogi-hub, 2026-04-16) counted commits-per-file without reading diff content; the fix is to force per-commit action assignment in a file.
+
+**Mechanical invariants (gate blocks on violation):**
+
+1. For every commit in `git log <base>..<branch>`, the plan MUST contain one line starting with the short SHA and a tagged action. No commits in an "unaccounted" bucket.
+2. Allowed actions: `port | adapt | skip-style | superseded | skip-with-reason`.
+3. `git log <base>..<branch> | wc -l` MUST equal the count of SHA-prefixed lines in the plan. Mismatch → hard-stop until reconciled.
+4. `skip-with-reason` entries MUST include a one-line reason after a `—` (em dash).
+
+**Structural-change detection (before plan write):**
+
+Run the structure-change sensor (`scripts/flow-structure-sensor.js`) on the diff. If ≥ `config.finalization.mergePlan.restructureThreshold` (default **20%**) of changed files match one of these restructure patterns, display a STRUCTURAL CHANGE warning at the top of the plan and bias the default action for affected commits to `adapt`:
+
+| Pattern | Example | Meaning |
+|---------|---------|---------|
+| `X.tsx` deleted + `X/X.tsx` added | `Card.tsx` → `Card/Card.tsx` | folder-per-component |
+| `X.ts` deleted + `<dir>/X.ts` added at deeper depth | `utils.ts` → `utils/date.ts` | split into submodule |
+| `X` deleted + `X.<ext>` added elsewhere | `types.ts` → `types/index.ts` | barrel introduction |
+
+**Procedure:**
+
+```bash
+# 1. Gather commit list
+git log --pretty='%h %s' <base>..<branch> > .workflow/scratch/.merge-plan-commits.txt
+
+# 2. Run structure sensor
+node node_modules/wogiflow/scripts/flow-structure-sensor.js <base>..<branch> > .workflow/scratch/.merge-plan-sensor.json
+
+# 3. Write .workflow/scratch/merge-plan.md using the template below,
+#    one SHA-prefixed line per commit. Read the FULL diff of each commit
+#    (not just the subject line) before assigning an action — that is
+#    the whole point of this gate.
+
+# 4. Verify the mechanical invariant
+test "$(git log --oneline <base>..<branch> | wc -l)" -eq \
+     "$(grep -cE '^[a-f0-9]{7,}\s' .workflow/scratch/merge-plan.md)"
+```
+
+**Plan template** (write verbatim, then fill each row by reading the full diff):
+
+```markdown
+# Merge plan: <branch> → <base>
+
+Commits: N (from `git log <base>..<branch>`)
+Structural-change sensor: <WARN|clean>  — N/M files match restructure patterns
+Cross-repo impact: <list workspace members affected, or "single-repo">
+
+## Per-commit actions
+
+| SHA | Subject | Action | Notes |
+|-----|---------|--------|-------|
+| abc1234 | feat: add login form | port | — |
+| def5678 | refactor: split Card.tsx into Card/ | adapt | folder-per-component restructure |
+| ghi9012 | chore: lint fixes | skip-style | — |
+| jkl3456 | revert: roll back header | skip-with-reason | superseded by mno7890 |
+
+## Structural risks
+
+<leave empty if sensor is clean; otherwise list each pattern hit>
+
+## Content risks
+
+<list overlaps in shared types, DTOs, API surface that need manual review>
+```
+
+**When the plan is complete**, the gate verifies the commit-count invariant (step 4) and proceeds to Step 3 (options). If invariant fails, the command stops with the reconciliation command printed.
+
+**Skip conditions:**
+- `config.finalization.mergePlan.enabled: false` — opt-out for users who don't want the gate
+- Branch commits ≤ threshold AND single-repo — small merges don't need a plan
+
 ### Step 3: Present Options
 
 ```
@@ -241,6 +314,12 @@ When `/wogi-start` completes a task that was executed in a worktree, the finaliz
       "includeTaskSpec": true,
       "includeCommitList": true,
       "includeFileSummary": true
+    },
+    "mergePlan": {
+      "enabled": true,
+      "threshold": 5,
+      "restructureThreshold": 0.20,
+      "alwaysForCrossRepo": true
     }
   }
 }
@@ -254,6 +333,10 @@ When `/wogi-start` completes a task that was executed in a worktree, the finaliz
 | `requirePRForTypes` | `[]` | Task types that must create a PR (useful for teams) |
 | `squashOnMerge` | `true` | Squash commits when merging |
 | `prTemplate` | `{...}` | What to include in auto-generated PR body |
+| `mergePlan.enabled` | `true` | Require per-commit merge plan on large or cross-repo merges |
+| `mergePlan.threshold` | `5` | Commit count above which the merge plan is required |
+| `mergePlan.restructureThreshold` | `0.20` | % of changed files matching restructure patterns that triggers a structural-change warning |
+| `mergePlan.alwaysForCrossRepo` | `true` | Require the plan on any cross-repo merge regardless of commit count |
 
 ## Examples
 

package/.claude/commands/wogi-start.md

@@ -180,18 +180,18 @@ When epic creation adds 2+ stories to ready.json and `config.bulkOrchestrator.en
 
 Non-blocking if transition fails.
 
-### Effort Level Optimization (Claude Code 2.1.72+)
+### Effort Level Optimization (Claude Code 2.1.72+, xhigh added 2.1.111+)
 
 After task level classification (L0-L3), set the reasoning effort level to optimize token usage:
 
 | Task Level | Effort | Rationale |
 |------------|--------|-----------|
-| L0 (Epic) | high | Complex planning, multi-file architecture |
+| L0 (Epic) | high (xhigh on Opus 4.7 for deep architectural reasoning) | Complex planning, multi-file architecture |
 | L1 (Story) | high | Multi-criteria implementation |
 | L2 (Task) | medium | Standard 1-5 file changes |
 | L3 (Subtask) | low | Single file, trivial change |
 
-This is advisory — Claude Code 2.1.72 simplified effort to low/medium/high (removed "max"). The AI should adjust its reasoning depth accordingly during implementation phases.
+This is advisory. Claude Code's effort levels: `low` / `medium` / `high` are universal. Claude Code 2.1.111+ added `xhigh` (between high and max) and `max` as Opus 4.7-only levels — other models fall back to `high`. Use `/effort` interactively (slider as of 2.1.111) to switch mid-session. The AI should adjust reasoning depth during implementation phases accordingly.
 
 ### Task Checkpoints (when `config.proactiveCompaction.enabled`)
 

package/.claude/commands/wogi-story.md

@@ -8,11 +8,38 @@ Run `./scripts/flow story "<title>"` to create a story.
 
 Load `agents/story-writer.md` for the full story format.
 
+## Anti-Deferral Rule (MANDATORY)
+
+**Every item the user provides MUST become a work item** (criterion or sub-task). Never silently filter items. If you believe an item should be deferred, **ASK the user** — do not decide autonomously.
+
+For multi-item inputs, the command output MUST include: **"All {N} items captured as {criteria|sub-tasks}."** If any item cannot be mapped, the "Unmapped" warning must be surfaced, not suppressed.
+
+This rule applies equally to deep-decomposition mode and flat stories.
+
+## Specification-Quality Gates (wf-63c0f4cc)
+
+Five P0 gates run automatically at creation time (all fail-open):
+
+| Gate | Fires When | Effect |
+|------|-----------|--------|
+| 1. Long Input | input ≥40 lines OR ≥5 discrete items | routes to `/wogi-extract-review` |
+| 2. Item Reconciliation | input has ≥3 discrete items | writes manifest, verifies coverage |
+| 3. Consumer Impact | input contains refactor/rename/migrate/etc. | greps consumers, flags phased migration at ≥5 breaking |
+| 4. Scope-Confidence | input mentions "new X" / "existing Y" / "the Z service" | audits assumptions → "Pending Clarifications" block |
+| 5. Intent Bootstrap | IGR artifacts missing + not already scheduled | schedules background bootstrap via session-state.json |
+
+Gates enforce **specification quality at creation time**; runtime-quality gates (wiring, typecheck, tests) remain `/wogi-start`'s job.
+
+Config: `storyFlow.consumerImpactAnalysis`, `storyFlow.scopeConfidenceAudit`, `storyFlow.itemReconciliation`. All default-true.
+
 ## Options
 
 - `--deep` - Enable deep decomposition mode (auto-generate granular sub-tasks)
 - `--priority <P>` - Set priority P0-P4 (default: P2 from config)
 - `--json` - Output JSON for programmatic access
+- `--skip-gates` - Skip all P0 gates (testing/debug only)
+- `--bypass-long-input` - Skip Gate 1 (set by `/wogi-start` when it already routed long input)
+- `--full-input <txt>` - Full user input for gates (when title is a summary)
 
 Examples:
 ```bash

package/.claude/docs/claude-code-compatibility.md

@@ -408,6 +408,37 @@ await cancelTask('wf-123', 'superseded', false);
 
 - **Hardened "Open in editor" against command injection**: Security hardening for untrusted filenames. **Impact on WogiFlow**: Validates the same pattern in `.claude/rules/security/security-patterns.md` — external inputs going into shell commands must be validated. No WogiFlow code change needed.
 
+### Features in 2.1.111+
+
+- **`xhigh` effort level for Opus 4.7**: New effort level sitting between `high` and `max`, available via `/effort`, `--effort`, and the model picker. Other models fall back to `high`. `/effort` now opens an interactive slider when called without arguments. **Impact on WogiFlow**: The effort-level mapping in `wogi-start.md` now acknowledges `xhigh`/`max` as Opus 4.7-only. For L0 epics running on Opus 4.7, users may prefer `xhigh` over `high` for deeper architectural reasoning — the mapping table documents this as an option. No code change needed; the mapping is advisory.
+
+- **`/ultrareview` built-in command**: Claude Code now ships a native `/ultrareview` that runs parallel multi-agent analysis and critique in the cloud — invoke with no arguments to review the current branch, or `/ultrareview <PR#>` to fetch and review a specific GitHub PR. **Relationship to WogiFlow's review commands**: No collision (`wogi-*` prefix). How to choose:
+  - `/ultrareview` — cloud-side parallel multi-agent critique. Zero local setup. Best for standalone branch/PR reviews when you don't have peer models configured.
+  - `/wogi-peer-review` — uses the peer models you configured via `/wogi-models-setup` (local/BYO models). Best when you want specific perspectives (e.g., a different vendor's model) or offline/cost-controlled review.
+  - `/wogi-review` — single-reviewer code review wired into WogiFlow task state (findings logged to `last-review.json`, triaged via `/wogi-triage`). Best for in-flow review during task execution.
+  - `/wogi-review-fix` — auto-applies fixes from `/wogi-review` findings.
+  Users can combine them: run `/ultrareview` for a wide-angle cloud critique, then `/wogi-review` for task-linked findings.
+
+- **`/less-permission-prompts` built-in skill**: Scans recent transcripts for common read-only Bash and MCP tool calls and proposes a prioritized allowlist for `.claude/settings.json`. **Relationship to WogiFlow**: Complementary to `computeLeanConfig()` in `lib/installer.js` — the installer produces a minimal allowlist at install time, while `/less-permission-prompts` tunes the allowlist based on actual session usage. Suggested workflow: after a few WogiFlow sessions, run `/less-permission-prompts` to prune redundant prompts. Future opportunity: surface this suggestion in `/wogi-health` output.
+
+- **Auto-allow for read-only bash with globs and `cd <project-dir> &&` prefix**: Read-only commands like `ls *.ts` and commands starting with `cd <project-dir> &&` no longer trigger a permission prompt. **Impact on WogiFlow**: Reduces prompts during WogiFlow hook-driven validation (lint/typecheck) and user-driven exploration. Allowlist rules in `lib/installer.js` that duplicated these patterns are now redundant — minor cleanup opportunity (tracked, low priority). No action required; the installer's lean-config approach already avoids over-emitting.
+
+- **Auto mode for Max subscribers on Opus 4.7**: Auto mode is now available for Max subscribers when using Opus 4.7, and no longer requires `--enable-auto-mode`. 2.1.112 fixed a "claude-opus-4-7 is temporarily unavailable" error in auto mode. **Impact on WogiFlow**: WogiFlow's model registry already lists Opus 4.7 (v2.22.0); auto-mode routing is orthogonal to WogiFlow's hybrid mode. Users on Max with Opus 4.7 benefit automatically.
+
+- **`OTEL_LOG_RAW_API_BODIES` env var**: Emits full API request and response bodies as OpenTelemetry log events for debugging. **Impact on WogiFlow**: Useful when debugging hybrid mode (`/wogi-hybrid`) routing and peer-review (`/wogi-peer-review`) model calls — set this env var to see the exact payloads reaching each model. Complements WogiFlow's gate telemetry (`/wogi-gate-stats`) which tracks pass/catch/miss rates at a higher level. Set with: `export OTEL_LOG_RAW_API_BODIES=1`. Note: payloads may contain sensitive data — only enable in development.
+
+- **Headless `--output-format stream-json` includes `plugin_errors` on init**: Plugin demotion errors (unsatisfied dependencies, conflicting versions) are now surfaced on the init event in headless mode. **WogiFlow opportunity**: `/wogi-health` could read this stream when running in CI/headless mode to flag plugin-registry issues before they cause silent failures. Tracked as an enhancement.
+
+- **Opus 4.7 availability fix (2.1.112)**: Fixed a "claude-opus-4-7 is temporarily unavailable" error in auto mode. Aligned with WogiFlow v2.22.0 registry update. No WogiFlow code change needed.
+
+- **Windows improvements**: `CLAUDE_ENV_FILE` and SessionStart hook environment files now apply on Windows (previously a no-op). Permission rules with drive-letter paths are now correctly root-anchored, and paths differing only by drive-letter case are recognized as the same path. **Impact on WogiFlow**: Windows users of WogiFlow's SessionStart hook can now configure environment variables via `CLAUDE_ENV_FILE`. Drive-letter-path permission rules generated by the installer now behave correctly. Automatic improvement after upgrade.
+
+- **Miscellaneous UX**: Plan files named after the originating prompt (e.g. `fix-auth-race-snug-otter.md`), `/skills` menu supports sorting by estimated token count (press `t`), Ctrl+U clears the entire input buffer (Ctrl+Y restores), Ctrl+L forces a full redraw, and typo suggestions on near-miss subcommands. Documentation-only for WogiFlow.
+
+- **Fixed "Unknown skill: commit" error**: Users without a custom `/commit` skill were seeing this error when Claude Code tried to invoke a non-existent built-in. **Impact on WogiFlow**: No WogiFlow-shipped `/commit` skill (commits go through `/wogi-finalize` and git commit instructions). Users benefit passively from the fix.
+
+- **Reliability fixes (all automatic after upgrade)**: Terminal display tearing in iTerm2+tmux, `@`-file suggestions re-scanning entire project in non-git directories, LSP diagnostics from before an edit appearing after it, tab-completing `/resume` behavior, `/context` grid rendering, `/clear` dropping session name, spurious decompression/network/transient errors in the TUI. Reverted v2.1.110 cap on non-streaming fallback retries (now uncapped again). Fixed Bedrock/Vertex/Foundry 429 retries pointing users at the wrong status page, bare URLs unclickable when wrapped in tool output, feedback surveys appearing back-to-back. WogiFlow sessions benefit from all of these automatically.
+
 ### Simple Mode Naming Distinction
 
 Claude Code's `CLAUDE_CODE_SIMPLE` environment variable (which enables a simplified tool set) is **unrelated** to WogiFlow's `loops.simpleMode` (a lightweight task completion loop using string detection). They are separate features that happen to share the word "simple":
@@ -542,4 +573,4 @@ Run `/keybindings` in Claude Code to customize your shortcuts.
 
 ---
 
-*Last updated: 2026-04-16*
+*Last updated: 2026-04-17*

package/.claude/rules/_internal/self-maintenance.md

@@ -75,7 +75,7 @@ Don't confuse them. `agents/security.md` (persona) is different from `.workflow/
 
 When modifying flow-*.js scripts:
 - Run `node --check scripts/<file>.js` after edits
-- WogiFlow has no test suite - syntax checking is the safety net
+- Run `npm test` — WogiFlow has a native-Node test suite (50+ files under `tests/`, 1800+ assertions) covering hooks, flow-io, security, session state, workspace gates, and more
 - Check for circular dependencies when moving shared functions
 
 ## 8. Feature Refactoring Cleanup

package/.claude/settings.json

@@ -170,6 +170,6 @@
   },
   "_comment_dynamicHooks": "TaskCreated (2.1.84+) and PermissionDenied (2.1.88+) are added by postinstall.js when the CC version supports them. They must NOT be committed statically — CC rejects the entire settings file if it encounters an unknown hook event name.",
   "_wogiFlowManaged": true,
-  "_wogiFlowVersion": "2.17.5",
+  "_wogiFlowVersion": "2.22.0",
   "_comment": "Shared WogiFlow hook configuration. Committed to repo for team use. User-specific overrides go in settings.local.json."
 }

package/lib/commands/login.js

@@ -414,7 +414,7 @@ async function login(args) {
         console.error(`\n\nServer error (${tokenResponse.statusCode}). Retrying...`);
         process.stdout.write('x');
       }
-    } catch (err) {
+    } catch (_err) {
       process.stdout.write('x');
     }
   }

package/lib/installer.js

@@ -194,7 +194,7 @@ function detectProjectScripts(projectRoot) {
   let pkgData;
   try {
     pkgData = safeReadJson(packageJsonPath);
-  } catch (err) {
+  } catch (_err) {
     return detected;
   }
 
@@ -989,7 +989,7 @@ async function init(args) {
       try {
         const analyzer = require('../scripts/flow-project-analyzer');
         detection = analyzer.detectProjectType(projectRoot);
-      } catch (err) {
+      } catch (_err) {
         // Fallback: use basic projectType from installer's own detection
         detection = {
           projectType: config.projectType || 'unknown',
@@ -1030,7 +1030,7 @@ async function init(args) {
         // Non-fatal — profile can be generated later via /wogi-test
       }
     }
-  } catch (err) {
+  } catch (_err) {
     // Non-fatal — flow-verification-profile may not exist yet during initial install
   }
 
@@ -1083,7 +1083,7 @@ function updateManifestAfterInit(cliDir) {
     if (!manifest || !Array.isArray(manifest.files)) {
       manifest = { version: 1, files: [], directories: ['.workflow'] };
     }
-  } catch (err) {
+  } catch (_err) {
     // No manifest yet — create a fresh one
     manifest = { version: 1, files: [], directories: ['.workflow'] };
   }
@@ -1129,7 +1129,7 @@ function walkDirForManifest(dir, baseDir, fileSet) {
         fileSet.add(path.relative(baseDir, fullPath));
       }
     }
-  } catch (err) {
+  } catch (_err) {
     // Non-critical — skip unreadable dirs
   }
 }

package/lib/release-channel.js

@@ -128,7 +128,7 @@ async function getLatestVersion(channel) {
     // Get version for the channel's npm tag
     const distTags = pkg['dist-tags'] || {};
     return distTags[channelConfig.npmTag] || distTags.latest || pkg.version;
-  } catch (err) {
+  } catch (_err) {
     return null;
   }
 }

package/lib/skill-registry.js

@@ -154,7 +154,7 @@ async function fetchSkillIndex(projectRoot) {
       throw new Error('Invalid index data');
     }
     return parsed;
-  } catch (err) {
+  } catch (_err) {
     // Return mock index for development/offline
     return {
       version: '1.0',
@@ -201,7 +201,7 @@ async function fetchSkillManifest(skillName, projectRoot) {
       throw new Error('Invalid manifest data');
     }
     return parsed;
-  } catch (err) {
+  } catch (_err) {
     throw new Error(`Skill '${skillName}' not found in registry`);
   }
 }
@@ -213,7 +213,7 @@ async function fetchSkillManifest(skillName, projectRoot) {
  * @param {string} projectRoot - Project root directory
  * @returns {Promise<Object>} Downloaded files
  */
-async function downloadSkillFiles(skillName, manifest, projectRoot) {
+async function downloadSkillFiles(skillName, manifest, _projectRoot) {
   const files = {};
   const baseUrl = `${REGISTRY_CONFIG.baseUrl}/${REGISTRY_CONFIG.branch}/skills/${skillName}`;
 

package/lib/workspace-dispatch-tracking.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Workspace — Dispatch Tracking (wf-d3e67abe)
+ *
+ * Silent-worker-halt detection via file-based dispatch records.
+ *
+ * Manager records every dispatch; any pending dispatch past its
+ * expectedDeadline without a matching completion/stop message =
+ * silent death. Surfaced on the next manager turn via the
+ * UserPromptSubmit hook (no background processes).
+ *
+ * State file: .workspace/state/dispatched-tasks.json
+ * Ring buffer of last MAX_ACTIVE records; older overflow to
+ * .workspace/state/dispatched-tasks.archive.jsonl (append-only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { safeReadJson } = require('./utils');
+
+const DEFAULT_DURATION_MS = 30 * 60 * 1000; // 30 min — matches waitForCompletion default
+const MAX_ACTIVE = 100;
+const SCHEMA_VERSION = 1;
+
+const VALID_STATUSES = new Set(['pending', 'completed', 'graceful-stop', 'silent-halt']);
+
+function stateFilePath(workspaceRoot) {
+  return path.join(workspaceRoot, '.workspace', 'state', 'dispatched-tasks.json');
+}
+
+function archiveFilePath(workspaceRoot) {
+  return path.join(workspaceRoot, '.workspace', 'state', 'dispatched-tasks.archive.jsonl');
+}
+
+function loadState(workspaceRoot) {
+  const data = safeReadJson(stateFilePath(workspaceRoot), null);
+  if (data && typeof data === 'object' && Array.isArray(data.dispatches)) {
+    return { version: data.version || SCHEMA_VERSION, dispatches: data.dispatches };
+  }
+  return { version: SCHEMA_VERSION, dispatches: [] };
+}
+
+function saveState(workspaceRoot, state) {
+  const filePath = stateFilePath(workspaceRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
+}
+
+function archiveRecord(workspaceRoot, record) {
+  const filePath = archiveFilePath(workspaceRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, JSON.stringify(record) + '\n');
+}
+
+/**
+ * Record a dispatch. Appends to state and trims ring buffer.
+ *
+ * @param {string} workspaceRoot
+ * @param {Object} params
+ * @param {string} params.taskId - wf-XXXXXXXX
+ * @param {string} params.repoName
+ * @param {number} [params.expectedDurationMs=DEFAULT_DURATION_MS]
+ * @param {string} [params.dispatchedBy='manager']
+ * @returns {Object} the created record
+ */
+function recordDispatch(workspaceRoot, { taskId, repoName, expectedDurationMs, dispatchedBy }) {
+  if (!workspaceRoot || typeof workspaceRoot !== 'string') {
+    throw new Error('workspaceRoot required');
+  }
+  if (!/^wf-[0-9a-f]{8}$/i.test(taskId || '')) {
+    throw new Error(`Invalid taskId: ${taskId}`);
+  }
+  if (!repoName || typeof repoName !== 'string') {
+    throw new Error('repoName required');
+  }
+
+  const durationMs = Number.isFinite(expectedDurationMs) && expectedDurationMs > 0
+    ? expectedDurationMs
+    : DEFAULT_DURATION_MS;
+  const now = Date.now();
+  const dispatchedAt = new Date(now).toISOString();
+  const expectedDeadline = new Date(now + durationMs).toISOString();
+
+  const record = {
+    taskId,
+    repoName,
+    dispatchedAt,
+    expectedDeadline,
+    expectedDurationMs: durationMs,
+    status: 'pending',
+    dispatchedBy: dispatchedBy || 'manager',
+    reconciledAt: null,
+    reconciledReason: null
+  };
+
+  const state = loadState(workspaceRoot);
+  state.dispatches.push(record);
+
+  // Ring buffer: overflow oldest records to archive
+  while (state.dispatches.length > MAX_ACTIVE) {
+    const overflow = state.dispatches.shift();
+    try { archiveRecord(workspaceRoot, overflow); }
+    catch (_err) { /* non-fatal — archive is best-effort */ }
+  }
+
+  saveState(workspaceRoot, state);
+  return record;
+}
+
+/**
+ * Reconcile the most recent pending record for a task.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} taskId
+ * @param {string} status - 'completed' | 'graceful-stop' | 'silent-halt'
+ * @param {string} [reason]
+ * @returns {Object|null} updated record, or null if not found
+ */
+function reconcileDispatch(workspaceRoot, taskId, status, reason) {
+  if (!VALID_STATUSES.has(status) || status === 'pending') {
+    throw new Error(`Invalid reconcile status: ${status}`);
+  }
+  const state = loadState(workspaceRoot);
+  // Find most recent pending record for this taskId (last wins — most recent dispatch)
+  for (let i = state.dispatches.length - 1; i >= 0; i--) {
+    const r = state.dispatches[i];
+    if (r && r.taskId === taskId && r.status === 'pending') {
+      r.status = status;
+      r.reconciledAt = new Date().toISOString();
+      r.reconciledReason = reason || null;
+      saveState(workspaceRoot, state);
+      return r;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read all currently-active dispatch records (not archived).
+ *
+ * @param {string} workspaceRoot
+ * @returns {Array<Object>}
+ */
+function readDispatches(workspaceRoot) {
+  return loadState(workspaceRoot).dispatches;
+}
+
+/**
+ * Get dispatches whose expectedDeadline has passed and are still pending.
+ *
+ * @param {string} workspaceRoot
+ * @param {number} [now=Date.now()]
+ * @returns {Array<Object>} overdue records
+ */
+function getOverdueDispatches(workspaceRoot, now) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const dispatches = readDispatches(workspaceRoot);
+  return dispatches.filter(r => {
+    if (!r || r.status !== 'pending') return false;
+    const deadline = Date.parse(r.expectedDeadline || '');
+    return Number.isFinite(deadline) && deadline < ts;
+  });
+}
+
+module.exports = {
+  DEFAULT_DURATION_MS,
+  MAX_ACTIVE,
+  recordDispatch,
+  reconcileDispatch,
+  readDispatches,
+  getOverdueDispatches,
+  stateFilePath,
+  archiveFilePath
+};

package/lib/workspace-events.js

@@ -46,7 +46,7 @@ const EVENT_TYPES = [
 
 const EVENTS_FILE = 'events.json';
 const MAX_EVENTS = 500; // Keep last 500 events
-const EVENT_ID_PATTERN = /^evt-[a-f0-9]{8}$/;
+const _EVENT_ID_PATTERN = /^evt-[a-f0-9]{8}$/;
 
 // ============================================================
 // Event Creation

package/lib/workspace-gates.js

@@ -470,7 +470,7 @@ function broadcastPostChange(workspaceRoot, fromRepo, context, options = {}) {
  * @param {Object} taskMeta
  * @returns {{ passed: boolean, message: string, severity: string }}
  */
-function gateDeploymentReadiness(workspaceRoot, context, taskMeta) {
+function gateDeploymentReadiness(workspaceRoot, _context, taskMeta) {
   const { execFileSync } = require('node:child_process');
 
   try {
@@ -668,7 +668,7 @@ function gatePeerNotification(workspaceRoot, context, taskMeta) {
  * Gate: cascadeVerification
  * For library repos, verify all consumers were notified.
  */
-function gateCascadeVerification(workspaceRoot, context, taskMeta) {
+function gateCascadeVerification(workspaceRoot, context, _taskMeta) {
   const gate = WORKSPACE_GATES.find(g => g.name === 'cascadeVerification');
 
   if (!context.currentMember || context.currentMember.role !== 'library') {

package/lib/workspace-intelligence.js

@@ -694,7 +694,7 @@ function analyzeReviewForCrossRepoImpact(workspaceRoot, manifest, changedFiles,
     result.endpointChanges = changedApiFiles;
 
     // Check if contract was also updated
-    const contractsDir = path.join(workspaceRoot, '.workspace', 'contracts');
+    const _contractsDir = path.join(workspaceRoot, '.workspace', 'contracts');
     const contractFiles = changedFiles.filter(f => f.includes('.workspace/contracts'));
 
     if (contractFiles.length === 0 && changedApiFiles.length > 0) {

package/lib/workspace-messages.js

@@ -22,6 +22,7 @@ const MESSAGE_TYPES = [
   'question',         // "Does your side handle X?"
   'bug-report',       // "Your endpoint returns 500 when I send Y"
   'task-complete',    // "I finished my side of feature Z"
+  'worker-stopped',   // Graceful Stop hook — worker session ending, not necessarily at task completion
   'needs-help',       // "I'm stuck, can you check X on your side?"
   'heads-up',         // "I'm about to change Y, just FYI"
   'impact-query',     // Pre-dev: "I'm about to change X, will this break you?"

package/lib/workspace-routing.js

@@ -344,7 +344,7 @@ function generateParallelInvestigation(workspaceRoot, bugDescription, manifest)
   const investigators = [];
 
   for (const [name, member] of Object.entries(manifest.members)) {
-    const repoPath = path.resolve(workspaceRoot, member.path);
+    const _repoPath = path.resolve(workspaceRoot, member.path);
 
     investigators.push({
       repoName: name,
@@ -700,6 +700,8 @@ function checkWorkerHealth(port) {
  * @param {string} taskId — task ID to start
  * @param {Object} [opts] — dispatch options
  * @param {string} [opts.effortLevel] — reasoning effort to propagate ('low'|'medium'|'high')
+ * @param {number} [opts.expectedDurationMs] — override deadline for silent-halt detection
+ *   (wf-d3e67abe). Defaults to DEFAULT_DURATION_MS from workspace-dispatch-tracking.
  * @returns {Promise<{ ok: boolean, message: string }>}
  */
 async function dispatchToChannel(workspaceRoot, repoName, taskId, opts = {}) {
@@ -739,6 +741,21 @@ async function dispatchToChannel(workspaceRoot, repoName, taskId, opts = {}) {
   const dispatchBody = `${effortPrefix}/wogi-start ${taskId}`;
   const result = await httpPost('127.0.0.1', port, dispatchBody);
   if (result.ok) {
+    // wf-d3e67abe — record dispatch for silent-halt detection.
+    // Fail-open: if tracking write fails, dispatch itself still succeeds.
+    try {
+      const { recordDispatch } = require('./workspace-dispatch-tracking');
+      recordDispatch(workspaceRoot, {
+        taskId,
+        repoName,
+        expectedDurationMs: opts.expectedDurationMs,
+        dispatchedBy: process.env.WOGI_REPO_NAME || 'manager'
+      });
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[dispatchToChannel] Dispatch tracking failed (non-fatal): ${err.message}`);
+      }
+    }
     return { ok: true, message: `Dispatched /wogi-start ${taskId} to ${repoName} (port ${port})${effortLevel ? ` [effort: ${effortLevel}]` : ''}` };
   }