gm-skill 2.0.1216 → 2.0.1218

package/README.md

@@ -35,7 +35,7 @@ An earlier generation fanned out fifteen per-platform downstream repos (gm-cc, g
 
 ## Version
 
-`2.0.1216` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
+`2.0.1218` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
 
 ## Source of truth
 

package/gm-plugkit/plugkit-wasm-wrapper.js

@@ -70,6 +70,32 @@ function isSpoolPollCommand(command) {
   return null;
 }
 
+function isBrowserRunningFileLocal(rel) {
+  if (!rel) return false;
+  const norm = String(rel).replace(/\\\\/g, '/');
+  if (/\\.(html?|tsx|jsx|vue|svelte)$/i.test(norm)) return true;
+  if (/\\.(mjs|cjs|js|ts|css|scss|sass)$/i.test(norm) && /^(src|public|site|app|pages|components|client|web)\\//i.test(norm)) return true;
+  return false;
+}
+
+function recordBrowserEditLocal(cwd, filePath) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    let rel = filePath;
+    try { rel = path.relative(cwd, filePath); } catch (_) {}
+    if (!isBrowserRunningFileLocal(rel)) return false;
+    const editsFile = path.join(cwd, '.gm', 'exec-spool', '.turn-browser-edits.json');
+    fs.mkdirSync(path.dirname(editsFile), { recursive: true });
+    let list = [];
+    try { list = JSON.parse(fs.readFileSync(editsFile, 'utf8')); if (!Array.isArray(list)) list = []; } catch (_) {}
+    const entry = { file: rel.replace(/\\\\/g, '/'), ts: Date.now() };
+    if (!list.some(e => e && e.file === entry.file)) list.push(entry);
+    fs.writeFileSync(editsFile, JSON.stringify(list));
+    return true;
+  } catch (_) { return false; }
+}
+
 let raw = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { raw += chunk; });
@@ -78,6 +104,17 @@ process.stdin.on('end', () => {
   try { event = JSON.parse(raw || '{}'); } catch (_) { event = {}; }
   const tool = event.tool_name || event.tool || '';
   const input = event.tool_input || event.input || {};
+  const cwd = event.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  if (tool === 'Write' || tool === 'Edit' || tool === 'MultiEdit') {
+    const fp = input.file_path || input.filePath || input.path || '';
+    if (fp) {
+      try { recordBrowserEditLocal(cwd, fp); } catch (_) {}
+    }
+    process.stdout.write(JSON.stringify({ continue: true }));
+    process.exit(0);
+  }
+
   if (tool !== 'Bash') {
     process.stdout.write(JSON.stringify({ continue: true }));
     process.exit(0);
@@ -124,11 +161,35 @@ function ensureSpoolPollGate(cwd) {
     const gateScript = path.join(gmHooks, 'spool-poll-gate.js');
     const want = spoolPollGateScript();
     let need = true;
+    let oldSha = '';
+    let existed = false;
     try {
       const existing = fs.readFileSync(gateScript, 'utf8');
+      existed = true;
       if (existing === want) need = false;
+      else {
+        try {
+          const _crypto = require('crypto');
+          oldSha = _crypto.createHash('sha256').update(existing).digest('hex').slice(0, 12);
+        } catch (_) {}
+      }
     } catch (_) {}
-    if (need) fs.writeFileSync(gateScript, want);
+    if (need) {
+      fs.writeFileSync(gateScript, want);
+      try {
+        const _crypto = require('crypto');
+        const newSha = _crypto.createHash('sha256').update(want).digest('hex').slice(0, 12);
+        try {
+          logEvent('bootstrap', existed ? 'gate.refreshed' : 'gate.installed', {
+            cwd,
+            path: gateScript,
+            old_sha: oldSha || null,
+            new_sha: newSha,
+            bytes: Buffer.byteLength(want, 'utf8'),
+          });
+        } catch (_) {}
+      } catch (_) {}
+    }
 
     const claudeDir = path.join(cwd, '.claude');
     fs.mkdirSync(claudeDir, { recursive: true });
@@ -141,15 +202,17 @@ function ensureSpoolPollGate(cwd) {
     if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
     if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
     const wantCommand = `node "\${CLAUDE_PROJECT_DIR}/.gm/hooks/spool-poll-gate.js"`;
-    let bashEntry = settings.hooks.PreToolUse.find(e => e && e.matcher === 'Bash');
-    if (!bashEntry) {
-      bashEntry = { matcher: 'Bash', hooks: [] };
-      settings.hooks.PreToolUse.push(bashEntry);
-    }
-    if (!Array.isArray(bashEntry.hooks)) bashEntry.hooks = [];
-    const already = bashEntry.hooks.some(h => h && typeof h.command === 'string' && h.command.includes('spool-poll-gate.js'));
-    if (!already) {
-      bashEntry.hooks.push({ type: 'command', command: wantCommand });
+    for (const matcher of ['Bash', 'Write', 'Edit', 'MultiEdit']) {
+      let entry = settings.hooks.PreToolUse.find(e => e && e.matcher === matcher);
+      if (!entry) {
+        entry = { matcher, hooks: [] };
+        settings.hooks.PreToolUse.push(entry);
+      }
+      if (!Array.isArray(entry.hooks)) entry.hooks = [];
+      const already = entry.hooks.some(h => h && typeof h.command === 'string' && h.command.includes('spool-poll-gate.js'));
+      if (!already) {
+        entry.hooks.push({ type: 'command', command: wantCommand });
+      }
     }
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   } catch (_) {}
@@ -172,6 +235,99 @@ function applyDisciplineSigil(rawBody) {
   return JSON.stringify(parsed);
 }
 
+function isInstructionTurnStart(sess) {
+  const key = sess || '(no-session)';
+  const now = Date.now();
+  const t = _turns.get(key);
+  if (!t) return true;
+  if ((now - t.lastTs) > TURN_IDLE_MS) return true;
+  return false;
+}
+
+function readUserPromptForRecall(cwd) {
+  const root = cwd || process.cwd();
+  try {
+    const p = path.join(root, '.gm', 'last-prompt.txt');
+    const txt = fs.readFileSync(p, 'utf8').trim();
+    if (txt) return txt;
+  } catch (_) {}
+  try {
+    const p = path.join(root, '.gm', 'turn-state.json');
+    const obj = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (obj && typeof obj.last_prompt === 'string' && obj.last_prompt.trim()) return obj.last_prompt.trim();
+    if (obj && typeof obj.prompt === 'string' && obj.prompt.trim()) return obj.prompt.trim();
+  } catch (_) {}
+  return '';
+}
+
+function dispatchVerbToWasmInternal(instance, verb, body) {
+  const dispatch = instance.exports.dispatch_verb;
+  if (!dispatch) return null;
+  const verbBytes = new TextEncoder().encode(verb);
+  const bodyBytes = new TextEncoder().encode(body || '');
+  const verbPtr = instance.exports.plugkit_alloc(verbBytes.length);
+  const bodyPtr = instance.exports.plugkit_alloc(bodyBytes.length);
+  try {
+    new Uint8Array(instance.exports.memory.buffer, verbPtr, verbBytes.length).set(verbBytes);
+    new Uint8Array(instance.exports.memory.buffer, bodyPtr, bodyBytes.length).set(bodyBytes);
+    const result = dispatch(verbPtr, verbBytes.length, bodyPtr, bodyBytes.length);
+    const ptr = Number(result & 0xffffffffn);
+    const len = Number(result >> 32n);
+    const out = new TextDecoder().decode(new Uint8Array(instance.exports.memory.buffer, ptr, len));
+    try { instance.exports.plugkit_free(ptr, len); } catch (_) {}
+    return out;
+  } finally {
+    try { instance.exports.plugkit_free(verbPtr, verbBytes.length); } catch (_) {}
+    try { instance.exports.plugkit_free(bodyPtr, bodyBytes.length); } catch (_) {}
+  }
+}
+
+function tryAutoRecallForTurnEntry(instance, sess, cwd) {
+  try {
+    const prompt = readUserPromptForRecall(cwd);
+    if (!prompt) return null;
+    const out = dispatchVerbToWasmInternal(instance, 'auto-recall', prompt);
+    if (!out) return null;
+    let parsed;
+    try { parsed = JSON.parse(out); } catch (_) { return null; }
+    if (!parsed || parsed.ok !== true) return null;
+    let inner = parsed.data;
+    if (typeof parsed.stdout === 'string' && parsed.stdout.length > 0) {
+      try { inner = JSON.parse(parsed.stdout); } catch (_) {}
+    }
+    if (!inner || typeof inner !== 'object') return null;
+    const hits = Array.isArray(inner.results) ? inner.results : (Array.isArray(inner.hits) ? inner.hits : []);
+    const payload = { query: inner.query || '', hits, fired_at: new Date().toISOString(), turn_entry: true };
+    logEvent('plugkit', 'auto_recall.turn-entry', { sess, query: payload.query, count: hits.length });
+    return payload;
+  } catch (e) {
+    logEvent('plugkit', 'auto_recall.error', { sess, error: String(e && e.message || e) });
+    return null;
+  }
+}
+
+function mergeAutoRecallIntoInstructionResponse(resultStr, autoRecall) {
+  if (!autoRecall) return resultStr;
+  let parsed;
+  try { parsed = JSON.parse(resultStr); } catch (_) { return resultStr; }
+  if (!parsed || typeof parsed !== 'object') return resultStr;
+  if (parsed.data && typeof parsed.data === 'object') {
+    parsed.data.auto_recall = autoRecall;
+  } else {
+    parsed.auto_recall = autoRecall;
+  }
+  if (typeof parsed.stdout === 'string' && parsed.stdout.length > 0) {
+    try {
+      const inner = JSON.parse(parsed.stdout);
+      if (inner && typeof inner === 'object') {
+        inner.auto_recall = autoRecall;
+        parsed.stdout = JSON.stringify(inner);
+      }
+    } catch (_) {}
+  }
+  return JSON.stringify(parsed);
+}
+
 function turnTick(sess, verb, taskBase, phase) {
   const key = sess || '(no-session)';
   const now = Date.now();
@@ -1203,6 +1359,8 @@ async function runSpoolWatcher(instance, spoolDir) {
   fs.mkdirSync(inDir, { recursive: true });
   fs.mkdirSync(outDir, { recursive: true });
 
+  try { ensureSpoolPollGate(process.env.CLAUDE_PROJECT_DIR || process.cwd()); } catch (_) {}
+
   const LOCK_PATH = path.join(spoolDir, '.watcher.lock');
   let _ownWrapperSha12 = '';
   try {
@@ -1506,18 +1664,35 @@ async function runSpoolWatcher(instance, spoolDir) {
     prior_status: _priorStatus,
     prior_status_age_ms: _priorStatus && Number.isFinite(_priorStatus.ts) ? Date.now() - _priorStatus.ts : null,
   };
-  const _isPlannedBoot = _priorShutdown && (_priorShutdown.reason === 'idle' || _priorShutdown.reason === 'sigterm' || _priorShutdown.reason === 'version-change');
+  const _PLANNED_REASONS = new Set(['idle', 'sigterm', 'version-change', 'wrapper-change', 'peer-stale-takeover', 'version-drift', 'external-planned']);
+  const _isPlannedBoot = _priorShutdown && _PLANNED_REASONS.has(_priorShutdown.reason);
   const _isFirstBoot = !_priorShutdown && !_priorStatus;
   const UNPLANNED_RESTART_MARKER = path.join(spoolDir, '.unplanned-restart.json');
-  if (!_isPlannedBoot && !_isFirstBoot) {
+  const HEARTBEAT_RECENT_MS = 60_000;
+  const HEARTBEAT_DEAD_MS = 5 * 60_000;
+  let _severity = 'critical';
+  if (_isPlannedBoot) {
+    _severity = 'info';
+  } else if (!_priorShutdown && _priorStatus && Number.isFinite(_priorStatus.ts)) {
+    const _statusAge = Date.now() - _priorStatus.ts;
+    if (_statusAge <= HEARTBEAT_RECENT_MS) _severity = 'warn';
+    else if (_statusAge < HEARTBEAT_DEAD_MS) _severity = 'warn';
+    else _severity = 'critical';
+  }
+  if (!_isFirstBoot) {
     const incidentPayload = {
       ts: Date.now(),
       version: _bootVersion,
-      severity: 'critical',
+      severity: _severity,
+      planned: _isPlannedBoot,
       ...restartContext,
       log_tail_path: path.join(spoolDir, '.watcher.log'),
       gm_log_dir: GM_LOG_ROOT,
-      instruction: 'Prior watcher died without a planned shutdown. This is treated as a critical failure. Inspect .watcher.log and gm-log/<day>/plugkit.jsonl events supervisor.watcher-exited-unexpectedly + supervisor.heartbeat-stale around the prior_status.ts timestamp to diagnose root cause.',
+      instruction: _isPlannedBoot
+        ? `Planned restart: prior watcher exited with reason="${_priorShutdown.reason}". No action required.`
+        : (_severity === 'warn'
+          ? 'Prior watcher disappeared with a recent heartbeat — likely a clean shutdown that did not write .shutdown-reason.json. Inspect .watcher.log if recurrent.'
+          : 'Prior watcher died without a planned shutdown and without a recent heartbeat. This is treated as a critical failure. Inspect .watcher.log and gm-log/<day>/plugkit.jsonl events supervisor.watcher-exited-unexpectedly + supervisor.heartbeat-stale around the prior_status.ts timestamp to diagnose root cause.'),
     };
     logEvent('plugkit', 'watcher.unplanned-restart', incidentPayload);
     try {
@@ -1575,6 +1750,14 @@ async function runSpoolWatcher(instance, spoolDir) {
       console.log(`[dispatch] → verb=${verb} task=${taskBase} body=${bodyBytes.length}b`);
       logEvent('plugkit', 'dispatch.start', { verb, task: taskBase, body_bytes: bodyBytes.length, cwd: process.cwd() });
 
+      let autoRecallPayload = null;
+      if (verb === 'instruction') {
+        const sessForRecall = readCurrentSess();
+        if (isInstructionTurnStart(sessForRecall)) {
+          autoRecallPayload = tryAutoRecallForTurnEntry(instance, sessForRecall, process.cwd());
+        }
+      }
+
       const verbPtr = instance.exports.plugkit_alloc(verbBytes.length);
       const bodyPtr = instance.exports.plugkit_alloc(bodyBytes.length);
       new Uint8Array(instance.exports.memory.buffer, verbPtr, verbBytes.length).set(verbBytes);
@@ -1585,7 +1768,11 @@ async function runSpoolWatcher(instance, spoolDir) {
       const ptr = Number(result & 0xffffffffn);
       const len = Number(result >> 32n);
       const resultBytes = new Uint8Array(instance.exports.memory.buffer, ptr, len);
-      const resultStr = new TextDecoder().decode(resultBytes);
+      let resultStr = new TextDecoder().decode(resultBytes);
+
+      if (autoRecallPayload) {
+        resultStr = mergeAutoRecallIntoInstructionResponse(resultStr, autoRecallPayload);
+      }
 
       const outName = dir === '.' ? `${taskBase}.json` : `${verb}-${taskBase}.json`;
       fs.writeFileSync(path.join(outDir, outName), resultStr);

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1216",
+  "version": "2.0.1218",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/lib/skill-bootstrap.js

@@ -363,6 +363,32 @@ function isSpoolPollCommand(command) {
   return null;
 }
 
+function isBrowserRunningFileLocal(rel) {
+  if (!rel) return false;
+  const norm = String(rel).replace(/\\\\/g, '/');
+  if (/\\.(html?|tsx|jsx|vue|svelte)$/i.test(norm)) return true;
+  if (/\\.(mjs|cjs|js|ts|css|scss|sass)$/i.test(norm) && /^(src|public|site|app|pages|components|client|web)\\//i.test(norm)) return true;
+  return false;
+}
+
+function recordBrowserEditLocal(cwd, filePath) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    let rel = filePath;
+    try { rel = path.relative(cwd, filePath); } catch (_) {}
+    if (!isBrowserRunningFileLocal(rel)) return false;
+    const editsFile = path.join(cwd, '.gm', 'exec-spool', '.turn-browser-edits.json');
+    fs.mkdirSync(path.dirname(editsFile), { recursive: true });
+    let list = [];
+    try { list = JSON.parse(fs.readFileSync(editsFile, 'utf8')); if (!Array.isArray(list)) list = []; } catch (_) {}
+    const entry = { file: rel.replace(/\\\\/g, '/'), ts: Date.now() };
+    if (!list.some(e => e && e.file === entry.file)) list.push(entry);
+    fs.writeFileSync(editsFile, JSON.stringify(list));
+    return true;
+  } catch (_) { return false; }
+}
+
 let raw = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { raw += chunk; });
@@ -371,6 +397,17 @@ process.stdin.on('end', () => {
   try { event = JSON.parse(raw || '{}'); } catch (_) { event = {}; }
   const tool = event.tool_name || event.tool || '';
   const input = event.tool_input || event.input || {};
+  const cwd = event.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  if (tool === 'Write' || tool === 'Edit' || tool === 'MultiEdit') {
+    const fp = input.file_path || input.filePath || input.path || '';
+    if (fp) {
+      try { recordBrowserEditLocal(cwd, fp); } catch (_) {}
+    }
+    process.stdout.write(JSON.stringify({ continue: true }));
+    process.exit(0);
+  }
+
   if (tool !== 'Bash') {
     process.stdout.write(JSON.stringify({ continue: true }));
     process.exit(0);
@@ -417,11 +454,33 @@ function ensureSpoolPollGate(cwd) {
     const gateScript = path.join(gmHooks, 'spool-poll-gate.js');
     const want = spoolPollGateScript();
     let need = true;
+    let oldSha = '';
+    let existed = false;
     try {
       const existing = fs.readFileSync(gateScript, 'utf8');
+      existed = true;
       if (existing === want) need = false;
+      else {
+        try {
+          const _crypto = require('crypto');
+          oldSha = _crypto.createHash('sha256').update(existing).digest('hex').slice(0, 12);
+        } catch (_) {}
+      }
     } catch (_) {}
-    if (need) fs.writeFileSync(gateScript, want);
+    if (need) {
+      fs.writeFileSync(gateScript, want);
+      try {
+        const _crypto = require('crypto');
+        const newSha = _crypto.createHash('sha256').update(want).digest('hex').slice(0, 12);
+        emitBootstrapEvent('info', existed ? 'gate.refreshed' : 'gate.installed', {
+          cwd,
+          path: gateScript,
+          old_sha: oldSha || null,
+          new_sha: newSha,
+          bytes: Buffer.byteLength(want, 'utf8'),
+        });
+      } catch (_) {}
+    }
 
     const claudeDir = path.join(cwd, '.claude');
     fs.mkdirSync(claudeDir, { recursive: true });
@@ -434,18 +493,22 @@ function ensureSpoolPollGate(cwd) {
     if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
     if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
     const wantCommand = `node "\${CLAUDE_PROJECT_DIR}/.gm/hooks/spool-poll-gate.js"`;
-    let bashEntry = settings.hooks.PreToolUse.find(e => e && e.matcher === 'Bash');
-    if (!bashEntry) {
-      bashEntry = { matcher: 'Bash', hooks: [] };
-      settings.hooks.PreToolUse.push(bashEntry);
-    }
-    if (!Array.isArray(bashEntry.hooks)) bashEntry.hooks = [];
-    const already = bashEntry.hooks.some(h => h && typeof h.command === 'string' && h.command.includes('spool-poll-gate.js'));
-    if (!already) {
-      bashEntry.hooks.push({ type: 'command', command: wantCommand });
+    let anyAlready = true;
+    for (const matcher of ['Bash', 'Write', 'Edit', 'MultiEdit']) {
+      let entry = settings.hooks.PreToolUse.find(e => e && e.matcher === matcher);
+      if (!entry) {
+        entry = { matcher, hooks: [] };
+        settings.hooks.PreToolUse.push(entry);
+      }
+      if (!Array.isArray(entry.hooks)) entry.hooks = [];
+      const already = entry.hooks.some(h => h && typeof h.command === 'string' && h.command.includes('spool-poll-gate.js'));
+      if (!already) {
+        entry.hooks.push({ type: 'command', command: wantCommand });
+        anyAlready = false;
+      }
     }
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    emitBootstrapEvent('info', 'Spool-poll gate ensured', { gateScript, settingsPath, hookAlreadyPresent: already });
+    emitBootstrapEvent('info', 'Spool-poll gate ensured', { gateScript, settingsPath, hookAlreadyPresent: anyAlready });
   } catch (e) {
     emitBootstrapEvent('warn', 'ensureSpoolPollGate failed', { error: e.message });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1216",
+  "version": "2.0.1218",
   "description": "Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation. Install in any AI coding agent host.",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "gm.json"
   ],
   "dependencies": {
-    "gm-plugkit": "^2.0.1216"
+    "gm-plugkit": "^2.0.1218"
   },
   "engines": {
     "node": ">=16.0.0"

package/prompts/prompt-submit.txt

@@ -66,6 +66,10 @@ Asking is permitted only as last resort — destructive-irreversible action with
 
 The size of the task, the cost of context, the duration of CI, and the number of repos involved are never grounds to ask. Neither is "this change touches files the user reads" — your job is to land the change correctly, not to defer to a review you imagine the user wants. Audit findings, prose rewrites, configuration edits, and refactors all ship inside the same turn as the analysis that produced them. Stopping mid-loop to ask "should I apply these?" is itself the deviation pattern: it routes the doubt back to the user instead of executing.
 
+=== AUTO-RECALL ON TURN ENTRY ===
+
+On every first `instruction` dispatch after a >30s idle gap (or at session-start), plugkit derives a 2–6 word recall query from `.gm/last-prompt.txt` / `.gm/turn-state.json` and attaches the resulting hits to the `instruction` response under the top-level field `auto_recall: {query, hits, fired_at, turn_entry: true}`. This is in addition to the existing `recall_hits` field (which is the phase+PRD-subject pack). Plugkit attaches the auto-recall pack to your instruction response on turn entry — YOU read it the same way you read `recall_hits`. Subsequent `instruction` dispatches in the same turn do not re-fire auto-recall; if you need a different query mid-turn, dispatch the `auto-recall` verb explicitly with your prompt as the body.
+
 === NO WAITING FOR PLUGKIT — HARD RULE ===
 
 Plugkit is synchronous from your perspective. You write the request file; the spool watcher processes it; you read the response file. There is no background work happening "while you wait." If you find yourself running `sleep 2; ls .gm/exec-spool/out/`, `Start-Sleep -Milliseconds 2500; Test-Path ...`, or any other poll-wait on the spool, you have misread the architecture. Read the response file directly with the Read tool — if it does not exist yet, the watcher is either dead (check `.gm/exec-spool/.status.json` mtime) or the verb is genuinely slow (check `.gm/exec-spool/.watcher.log` for the dispatch trace). Polling is forbidden. Wait-narration ("the orchestrator is processing, while waiting let me…") is a tell that you have lost the loop.

package/skills/gm-skill/SKILL.md

@@ -21,3 +21,5 @@ bun x gm-plugkit@latest spool > /dev/null 2>&1 &
 (`npx -y gm-plugkit@latest spool > /dev/null 2>&1 &` if `bun` missing.) Heartbeat fresh → YOU dispatch `instruction` — first turn body `{"prompt":"<user request>"}` so orient_nouns and recall_hits derive from the request; subsequent turns may use empty body. Read the response file directly with the Read tool. Never poll the spool dir with `sleep && ls` or `Start-Sleep && Test-Path` — plugkit is synchronous from your view; if the response is not there, the watcher is dead (check `.status.json` mtime) or the verb is slow (check `.watcher.log`), not "still processing."
 
 Response body is not a mutation surface. Memory writes route through `memorize-fire` only — another verb YOU dispatch.
+
+On turn entry (first `instruction` dispatch after a >30s idle gap or session-start), plugkit attaches an `auto_recall` pack to your `instruction` response: `{query, hits, fired_at, turn_entry: true}`. The query is derived from `.gm/last-prompt.txt` / `.gm/turn-state.json`; hits are the top recall results plugkit pulled before serving your instruction. Read `auto_recall.hits` alongside the existing `recall_hits` (which is the phase+PRD-subject pack) — both surface prior memory, but `auto_recall` is the per-turn user-prompt pack and only fires on turn entry. Subsequent `instruction` dispatches in the same turn carry no `auto_recall` field (or carry the same pack from the turn-start fire); do not re-trigger it manually.