wogiflow 2.22.1 → 2.22.2

package/lib/workspace-messages.js

@@ -23,6 +23,7 @@ const MESSAGE_TYPES = [
   '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
+  'worker-ready',     // Fresh worker session with empty queue — "got anything for me?" (wf-restart-handoff)
   '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-worker-ready.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Workspace — Worker Readiness Announce (restart-handoff protocol)
+ *
+ * Problem this solves:
+ *   When a worker session restarts (wogi-claude wrapper relaunches claude
+ *   after a task-boundary), channel dispatches sent by the manager during
+ *   the restart window can be lost — they arrive either while the old
+ *   claude is shutting down or before the new claude has wired up its
+ *   MCP channel, and the notification never reaches a live session.
+ *
+ *   Previous sessions observed: manager dispatches session N, worker
+ *   completes N and restarts, manager tries to dispatch N+1 during the
+ *   restart gap, N+1 is lost, worker comes up fresh with empty queue
+ *   and sits idle until the user notices and the manager re-dispatches.
+ *
+ * Design:
+ *   File-based announce via the workspace-messages bus. When a worker
+ *   SessionStart fires and the worker has zero in-progress tasks and
+ *   zero queued channel dispatches, write a structured `worker-ready`
+ *   message to `.workspace/messages/`. The manager's next turn sweeps
+ *   the bus, cross-references the dispatched-tasks.json (wf-d3e67abe)
+ *   to see if anything is owed to this worker, and surfaces lost
+ *   dispatches for re-dispatch.
+ *
+ *   File-based delivery is durable: no timing games, no buffer TTL,
+ *   no dependency on the MCP channel server being up during the
+ *   restart gap. Worker writes → manager reads → reconciles.
+ *
+ * Dedup:
+ *   If a pending `worker-ready` message already exists for this repo,
+ *   we skip — no need to stack announcements while the manager hasn't
+ *   picked up the first one yet.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { safeReadJson } = require('./utils');
+
+/**
+ * Detect if the current process is a workspace worker (not a manager and not a
+ * single-repo session). Mirrors the isWorkspaceWorker detection used in
+ * scripts/hooks/core/task-completed.js.
+ *
+ * @returns {boolean}
+ */
+function isWorker() {
+  if (!process.env.WOGI_WORKSPACE_ROOT) return false;
+  const repo = process.env.WOGI_REPO_NAME;
+  if (!repo || repo === 'manager') return false;
+  return true;
+}
+
+/**
+ * Resolve the workspace root from env (worker mode).
+ *
+ * @returns {string|null}
+ */
+function getWorkspaceRoot() {
+  const root = process.env.WOGI_WORKSPACE_ROOT;
+  if (!root || !path.isAbsolute(root)) return null;
+  return root;
+}
+
+/**
+ * Check whether a pending worker-ready message already exists for this repo.
+ * Used to dedup — we don't need to stack announcements.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} repoName
+ * @returns {boolean}
+ */
+function hasPendingAnnounce(workspaceRoot, repoName) {
+  try {
+    const messagesDir = path.join(workspaceRoot, '.workspace', 'messages');
+    if (!fs.existsSync(messagesDir)) return false;
+    const files = fs.readdirSync(messagesDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const msg = safeReadJson(path.join(messagesDir, file));
+        if (!msg) continue;
+        if (msg.type === 'worker-ready' &&
+            msg.from === repoName &&
+            msg.status === 'pending') {
+          return true;
+        }
+      } catch (_err) { /* skip malformed */ }
+    }
+    return false;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Decide whether this worker should announce ready.
+ * Preconditions:
+ *   - Worker mode (WOGI_WORKSPACE_ROOT + WOGI_REPO_NAME !== 'manager')
+ *   - ready.json has zero in-progress tasks
+ *   - ready.json has zero queued channel-dispatched tasks
+ *     (if it has queued work, the SessionStart hook auto-invokes
+ *     /wogi-start instead of announcing — different branch)
+ *   - No pending worker-ready message already exists for this repo
+ *
+ * @param {Object} [opts] - override knobs for testing
+ * @param {string} [opts.workspaceRoot]
+ * @param {string} [opts.repoName]
+ * @param {Object} [opts.readyData]
+ * @returns {{announce: boolean, reason: string, repoName?: string, workspaceRoot?: string}}
+ */
+function shouldAnnounceReady(opts = {}) {
+  const workspaceRoot = opts.workspaceRoot || getWorkspaceRoot();
+  const repoName = opts.repoName || process.env.WOGI_REPO_NAME;
+
+  if (!workspaceRoot) return { announce: false, reason: 'no-workspace-root' };
+  if (!opts.repoName && !isWorker()) return { announce: false, reason: 'not-worker' };
+  if (!repoName || repoName === 'manager') return { announce: false, reason: 'not-worker' };
+
+  let readyData = opts.readyData;
+  if (!readyData) {
+    try {
+      const { PATHS } = require('../scripts/flow-utils');
+      const readyPath = path.join(PATHS.state, 'ready.json');
+      readyData = safeReadJson(readyPath, { ready: [], inProgress: [] });
+    } catch (_err) {
+      readyData = { ready: [], inProgress: [] };
+    }
+  }
+
+  const inProgress = Array.isArray(readyData.inProgress) ? readyData.inProgress : [];
+  if (inProgress.length > 0) {
+    return { announce: false, reason: 'in-progress-not-empty' };
+  }
+
+  const queuedChannel = (Array.isArray(readyData.ready) ? readyData.ready : [])
+    .filter(t => t && (
+      t.channelSource === 'wogi-workspace-channel' ||
+      t.dispatchedBy === 'workspace-manager' ||
+      (typeof t.source === 'string' && t.source.startsWith('workspace:'))
+    ));
+  if (queuedChannel.length > 0) {
+    return { announce: false, reason: 'queued-channel-work-present' };
+  }
+
+  if (hasPendingAnnounce(workspaceRoot, repoName)) {
+    return { announce: false, reason: 'already-announced' };
+  }
+
+  return { announce: true, reason: 'ok', workspaceRoot, repoName };
+}
+
+/**
+ * Write a worker-ready message to the workspace-messages bus.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} repoName
+ * @returns {{written: boolean, messageId?: string, path?: string, reason?: string}}
+ */
+function announceWorkerReady(workspaceRoot, repoName) {
+  try {
+    const { createMessage, saveMessage } = require('./workspace-messages');
+    const msg = createMessage({
+      from: repoName,
+      to: 'manager',
+      type: 'worker-ready',
+      subject: `Worker ${repoName} ready — queue empty, awaiting dispatch`,
+      body: [
+        `Worker "${repoName}" has started a fresh session with an empty task queue.`,
+        `If you dispatched any tasks to this worker that were lost during the`,
+        `restart window, they can be re-dispatched now. No pending work detected`,
+        `in ready.json (zero inProgress, zero queued channel dispatches).`
+      ].join('\n'),
+      priority: 'medium',
+      actionRequired: false
+    });
+    const filePath = saveMessage(workspaceRoot, msg);
+    return { written: true, messageId: msg.id, path: filePath };
+  } catch (err) {
+    return { written: false, reason: `write-failed: ${err.message}` };
+  }
+}
+
+module.exports = {
+  isWorker,
+  getWorkspaceRoot,
+  hasPendingAnnounce,
+  shouldAnnounceReady,
+  announceWorkerReady
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "2.22.1",
+  "version": "2.22.2",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "flow": "./scripts/flow",
-    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/flow-story-gates.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
+    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/flow-story-gates.test.js tests/flow-workspace-restart-handoff.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
     "test:syntax": "find scripts/ lib/ -name '*.js' -not -path '*/node_modules/*' -exec node --check {} +",
     "lint": "eslint scripts/ lib/ tests/",
     "lint:ci": "eslint scripts/ lib/ tests/ --max-warnings 0",

package/scripts/hooks/core/overdue-dispatches.js

@@ -108,10 +108,122 @@ function sweepAndReconcile(workspaceRoot) {
   return reconciled;
 }
 
+/**
+ * Reconcile pending `worker-ready` messages (2.22.2 restart-handoff).
+ *
+ * A worker-ready message signals that a worker session started with an
+ * empty queue — possibly because a prior dispatch was lost during the
+ * wrapper's restart window. For each pending worker-ready:
+ *   - Find pending dispatches to that repo in dispatched-tasks.json
+ *   - If any found: they're likely the lost dispatches. Collect as
+ *     `lostDispatches` for surface to the manager.
+ *   - Mark the worker-ready message as acknowledged regardless — once
+ *     the manager has seen it, there's nothing more to do with the
+ *     same message. If another restart happens, a fresh worker-ready
+ *     will be written.
+ *
+ * @param {string} workspaceRoot
+ * @param {Object} [opts]
+ * @param {number} [opts.staleGraceMs=30000] — ignore dispatches newer than this
+ *   (to avoid flagging just-sent dispatches still in flight).
+ * @returns {{acknowledged: number, lostDispatches: Array}}
+ */
+function reconcileWorkerReady(workspaceRoot, opts = {}) {
+  const staleGraceMs = Number.isFinite(opts.staleGraceMs) ? opts.staleGraceMs : 30000;
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+
+  let readMessages, updateMessageStatus, readDispatches;
+  try {
+    const libMessages = path.resolve(__dirname, '..', '..', '..', 'lib', 'workspace-messages.js');
+    const libTracking = path.resolve(__dirname, '..', '..', '..', 'lib', 'workspace-dispatch-tracking.js');
+    const bus = require(libMessages);
+    readMessages = bus.readMessages;
+    updateMessageStatus = bus.updateMessageStatus;
+    const tracking = require(libTracking);
+    readDispatches = tracking.readDispatches;
+  } catch (_err) {
+    return { acknowledged: 0, lostDispatches: [] };
+  }
+
+  let pendingReady = [];
+  try {
+    pendingReady = readMessages(workspaceRoot, { type: 'worker-ready', status: 'pending' });
+  } catch (_err) {
+    return { acknowledged: 0, lostDispatches: [] };
+  }
+  if (pendingReady.length === 0) return { acknowledged: 0, lostDispatches: [] };
+
+  let dispatches = [];
+  try {
+    dispatches = readDispatches(workspaceRoot).filter(r => r && r.status === 'pending');
+  } catch (_err) {
+    dispatches = [];
+  }
+
+  const lostDispatches = [];
+  let acknowledged = 0;
+
+  for (const msg of pendingReady) {
+    const repoName = msg.from;
+    if (!repoName) continue;
+
+    // Find pending dispatches to this repo that are older than the grace
+    // period (avoid race conditions with just-sent dispatches).
+    const candidates = dispatches.filter(r => {
+      if (r.repoName !== repoName) return false;
+      const dispatched = Date.parse(r.dispatchedAt || '');
+      if (!Number.isFinite(dispatched)) return false;
+      return (now - dispatched) > staleGraceMs;
+    });
+
+    for (const c of candidates) {
+      lostDispatches.push({ ...c, workerReadyMsgId: msg.id });
+    }
+
+    // Acknowledge the worker-ready message — we've processed it once.
+    // If the restart-loss recurs, a fresh worker-ready will be written.
+    try {
+      if (updateMessageStatus) {
+        updateMessageStatus(workspaceRoot, msg.id, 'acknowledged');
+        acknowledged++;
+      }
+    } catch (_err) { /* non-fatal */ }
+  }
+
+  return { acknowledged, lostDispatches };
+}
+
+/**
+ * Format the lost-dispatches block for manager additionalContext.
+ *
+ * @param {Array} lost
+ * @returns {string|null}
+ */
+function formatLostDispatchesContext(lost) {
+  if (!Array.isArray(lost) || lost.length === 0) return null;
+  const lines = lost.map(r => {
+    const dispatchedAt = r.dispatchedAt || '?';
+    return `• ${r.taskId} → ${r.repoName}  | dispatched ${dispatchedAt} | still pending after worker restart`;
+  });
+  return [
+    `━━━ LOST DISPATCHES — WORKER RESTARTED WITH EMPTY QUEUE (${lost.length}) ━━━`,
+    ...lines,
+    '',
+    'A worker announced fresh readiness but these dispatches are still',
+    'pending. Likely lost during the wrapper\'s restart window. Re-dispatch',
+    'them now via dispatchToChannel(workspaceRoot, repoName, taskId).',
+    '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
+  ].join('\n');
+}
+
 /**
  * Build the overdue-dispatches additionalContext block, or return null
  * when nothing to surface (non-manager, no workspace root, no overdue).
  *
+ * Also handles worker-ready reconciliation (2.22.2) — if workers announced
+ * readiness and there are matching pending dispatches, include a lost-dispatch
+ * section so the manager can re-dispatch.
+ *
  * @param {Object} [opts]
  * @param {string} [opts.workspaceRoot] — override (primarily for tests)
  * @param {number} [opts.now=Date.now()]
@@ -128,32 +240,52 @@ function buildOverdueContext(opts = {}) {
   try { sweepAndReconcile(workspaceRoot); }
   catch (_err) { /* fail-open */ }
 
+  // Reconcile worker-ready announcements. Surface any lost dispatches
+  // the manager should re-send.
+  let lostBlock = null;
+  try {
+    const { lostDispatches } = reconcileWorkerReady(workspaceRoot, { now: opts.now });
+    lostBlock = formatLostDispatchesContext(lostDispatches);
+  } catch (_err) { /* fail-open */ }
+
   let overdue;
   try {
     const libPath = path.resolve(__dirname, '..', '..', '..', 'lib', 'workspace-dispatch-tracking.js');
     const { getOverdueDispatches } = require(libPath);
     overdue = getOverdueDispatches(workspaceRoot, opts.now);
   } catch (_err) {
-    return null; // Fail-open — tracking module missing or IO failure should never block the prompt.
+    // If dispatch-tracking is missing but we have lost-dispatches from
+    // worker-ready, still surface those.
+    return lostBlock;
   }
 
-  if (!Array.isArray(overdue) || overdue.length === 0) return null;
+  if ((!Array.isArray(overdue) || overdue.length === 0) && !lostBlock) return null;
 
-  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
-  const lines = overdue.map(r => formatLine(r, now));
-  return [
-    `━━━ OVERDUE WORKSPACE DISPATCHES (${overdue.length}) ━━━`,
-    ...lines,
-    '',
-    'These workers may have died silently. Check worker terminals;',
-    'if dead, re-dispatch or mark failed. Records:',
-    '  .workspace/state/dispatched-tasks.json',
-    '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
-  ].join('\n');
+  const sections = [];
+
+  if (lostBlock) sections.push(lostBlock);
+
+  if (Array.isArray(overdue) && overdue.length > 0) {
+    const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+    const lines = overdue.map(r => formatLine(r, now));
+    sections.push([
+      `━━━ OVERDUE WORKSPACE DISPATCHES (${overdue.length}) ━━━`,
+      ...lines,
+      '',
+      'These workers may have died silently. Check worker terminals;',
+      'if dead, re-dispatch or mark failed. Records:',
+      '  .workspace/state/dispatched-tasks.json',
+      '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
+    ].join('\n'));
+  }
+
+  return sections.length > 0 ? sections.join('\n\n') : null;
 }
 
 module.exports = {
   isManagerSession,
   buildOverdueContext,
-  sweepAndReconcile
+  sweepAndReconcile,
+  reconcileWorkerReady,
+  formatLostDispatchesContext
 };

package/scripts/hooks/core/session-context.js

@@ -871,6 +871,23 @@ function formatContextForInjection(context) {
     // Non-critical — history file may not exist; continue with normal context
   }
 
+  // Workspace worker auto-resume (wf-restart-handoff / 2.22.2).
+  // CRITICAL priority — shown at the top so the model acts on it before
+  // anything else. Fires when a worker session starts with queued channel
+  // dispatches that were inherited from the prior (restarted) session.
+  if (ctx.workerAutoResume) {
+    output += `### Workspace Worker Auto-Resume\n`;
+    output += ctx.workerAutoResume + '\n\n';
+  }
+
+  // Workspace worker readiness announcement (wf-restart-handoff / 2.22.2).
+  // Informational — worker started idle, announced readiness to manager.
+  // Manager will reconcile async; no immediate action required from the worker.
+  if (ctx.workerReadyAnnounce) {
+    output += `### Workspace Worker Ready\n`;
+    output += ctx.workerReadyAnnounce + '\n\n';
+  }
+
   // CRITICAL: CLAUDE_CODE_SIMPLE mode warning (highest priority)
   if (ctx.simpleModeWarning && ctx.simpleModeWarning.active) {
     output += `### CLAUDE_CODE_SIMPLE Mode Detected\n`;

package/scripts/hooks/core/session-start-worker.js

@@ -0,0 +1,114 @@
+/**
+ * Wogi Flow — Worker SessionStart handler (wf-restart-handoff)
+ *
+ * Handles the "worker just started" branch of SessionStart:
+ *
+ *   - If worker has queued channel dispatches in ready.json:
+ *     inject additionalContext telling the model to invoke
+ *     /wogi-start <nextId> now. Mirrors the existing Stop-hook
+ *     autopickup flow (task-completed.js::buildAutoPickupContext)
+ *     but fires at session boundary instead of turn boundary —
+ *     necessary because restart (wf-d3e67abe/2.22.1) kills the
+ *     previous claude and the Stop-hook autopickup no longer bridges
+ *     between tasks.
+ *
+ *   - Else if worker has zero in-progress + zero queued channel
+ *     dispatches: write a `worker-ready` message to the workspace
+ *     message bus so the manager can reconcile against its durable
+ *     dispatched-tasks.json and re-dispatch any work lost during
+ *     the restart window.
+ *
+ * Returns a context fragment (or null) that the SessionStart entry
+ * merges into the overall hook output.
+ *
+ * Fail-open: any error returns null and logs in DEBUG mode. Never
+ * blocks session startup.
+ */
+
+const path = require('node:path');
+
+const WORKER_READY_LIB = path.join(__dirname, '..', '..', '..', 'lib', 'workspace-worker-ready.js');
+const TASK_COMPLETED_CORE = path.join(__dirname, 'task-completed.js');
+
+/**
+ * Handle worker SessionStart.
+ *
+ * @returns {{branch: 'auto-resume'|'announce-ready'|'skip', context?: string, announced?: Object, pickup?: Object}}
+ */
+function handleWorkerSessionStart() {
+  try {
+    const { isWorker, shouldAnnounceReady, announceWorkerReady } = require(WORKER_READY_LIB);
+    if (!isWorker()) return { branch: 'skip', reason: 'not-worker' };
+
+    // Check for queued work first — if any, tell the model to pick it up
+    // instead of announcing idle readiness.
+    let pickup;
+    try {
+      const { findQueuedChannelDispatches, buildAutoPickupContext } = require(TASK_COMPLETED_CORE);
+      pickup = findQueuedChannelDispatches();
+      if (pickup && pickup.count > 0 && pickup.nextTaskId) {
+        const base = buildAutoPickupContext(pickup);
+        // Adjust the leading line for session-start context — the canonical
+        // pickup message starts with "You just completed a task." which isn't
+        // true on session start. Re-frame it here.
+        const context = [
+          `⚡ WORKSPACE SESSION START — ${pickup.count} CHANNEL DISPATCH${pickup.count === 1 ? '' : 'ES'} QUEUED`,
+          '',
+          `This fresh worker session has ${pickup.count} channel-dispatched task${pickup.count === 1 ? '' : 's'} queued in ready.json.`,
+          `The previous session restarted cleanly (wogi-claude wrapper). Pick up the next task now.`,
+          '',
+          `Next: ${pickup.nextTaskId} — ${pickup.nextTaskTitle || '(no title)'}`,
+          '',
+          'AUTONOMOUS MODE CONTRACT (workspace worker):',
+          '  • These dispatches are pre-approved by the manager.',
+          '  • You MUST start the next one IMMEDIATELY in this same turn.',
+          '  • Do NOT hedge ("awaiting signal", "let me know"). Forbidden.',
+          '',
+          `ACT NOW: Invoke Skill(skill="wogi-start", args="${pickup.nextTaskId}")`
+        ].join('\n');
+        // base included for logging/telemetry parity if we ever want to diff them
+        void base;
+        return { branch: 'auto-resume', context, pickup };
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[session-start-worker] pickup-check failed (fail-open): ${err.message}`);
+      }
+    }
+
+    // No queued work — announce readiness so the manager can reconcile.
+    const decision = shouldAnnounceReady();
+    if (!decision.announce) {
+      return { branch: 'skip', reason: decision.reason };
+    }
+
+    const announced = announceWorkerReady(decision.workspaceRoot, decision.repoName);
+    if (!announced.written) {
+      if (process.env.DEBUG) {
+        console.error(`[session-start-worker] announce failed: ${announced.reason}`);
+      }
+      return { branch: 'skip', reason: announced.reason };
+    }
+
+    // Optional context surface — not strictly needed since the manager
+    // handles reconciliation asynchronously, but a one-line note helps
+    // humans reading worker transcripts understand why the worker is idle.
+    const context = [
+      `Worker session started with empty queue.`,
+      `Announced readiness to manager (msg ${announced.messageId}) —`,
+      `manager will reconcile against its dispatch log and re-dispatch`,
+      `any work lost during the restart window.`
+    ].join(' ');
+
+    return { branch: 'announce-ready', context, announced };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[session-start-worker] unexpected error (fail-open): ${err.message}`);
+    }
+    return { branch: 'skip', reason: `error: ${err.message}` };
+  }
+}
+
+module.exports = {
+  handleWorkerSessionStart
+};

package/scripts/hooks/entry/claude-code/session-start.js

@@ -303,5 +303,27 @@ runHook('SessionStart', async ({ parsedInput }) => {
     }
   }
 
+  // Workspace worker restart-handoff (wf-restart-handoff / 2.22.2).
+  // When the wogi-claude wrapper restarts a worker (via task-boundary-reset),
+  // queued dispatches from the PRIOR session are picked up by auto-resume;
+  // if the queue is truly empty, announce worker-ready so the manager can
+  // reconcile against its dispatch log and re-dispatch anything lost during
+  // the restart window. See scripts/hooks/core/session-start-worker.js.
+  try {
+    const { handleWorkerSessionStart } = require('../../core/session-start-worker');
+    const workerResult = handleWorkerSessionStart();
+    if (workerResult.context && coreResult && coreResult.context) {
+      if (workerResult.branch === 'auto-resume') {
+        coreResult.context.workerAutoResume = workerResult.context;
+      } else if (workerResult.branch === 'announce-ready') {
+        coreResult.context.workerReadyAnnounce = workerResult.context;
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[session-start] Worker session-start handler failed: ${err.message}`);
+    }
+  }
+
   return coreResult;
 }, { failMode: 'warn' });