mtech-ai-local-runner 0.1.54 → 0.1.56

package/README.md

@@ -1,3 +1,48 @@
+## 0.1.56: AI-first asks count only prompts a person typed
+
+Claude Code runs UserPromptSubmit for turns nobody typed as well: an asyncRewake wake, a task notification, a message
+from another session, a side session's brief (Work Item e1c08b33, Work Decision cc8817f9). The ask hook client now
+classifies each prompt on this Mac and tells the hub only whether a person typed it, never the text.
+- A prompt nobody typed marks the session as in a turn and does nothing else: it does not show an ask, does not count one
+  as seen and does not make the session the one asks go to.
+- A typed prompt within 10 s of a wake or a stop show does not count that ask as seen.
+- An ask pinned to a session in a turn is shown at the next typed prompt in any session that becomes its chosen session
+  (PR #421), or at that session's turn end.
+
+The hub still accepts the prompt events of an older hook client and counts them as typed. `asks.json` gains an optional
+`lastTurnStartAt` per session. A session that was already open before the integration was installed has no hooks: start
+a new session, or run `/reload-plugins` in the terminal.
+
+## 0.1.55: guide hooks that steer AI sessions to the AI Gateway (disabled)
+
+The guide integration (Work Item d38d60f9) adds two hooks to Claude Code and Codex. Install it only on request:
+
+    npx mtech-ai-local-runner integrations install --feature guide
+    npx mtech-ai-local-runner setup --integrations claude,codex --feature asks,guide
+
+**Where it is installed**
+- Claude Code: a second skills-directory plugin, `mtec-ai-gateway-guide`.
+- Codex: two handlers in `~/.codex/hooks.json`. Trust them once, in the Codex app under Settings → Hooks or with `/hooks`
+  in the Codex CLI.
+- Both run the stable shim `<state root>/bin/gateway-guide-hook`.
+
+**What the hooks do**
+- They act only in sessions a person attends. The session must be in a company clone (origin on bitbucket.org in a
+  workspace the Gateway lists) or in a folder of such clones.
+- They remind the session to call `workspace_getting_started` and to search with `knowledge_search`.
+- They count KnowledgeBase reads, searches, Gateway tool calls and CLI commands that a Gateway tool covers.
+- A rule adds a line of text only after the Gateway moves it to `warn`.
+- Nothing is ever blocked, and no hook sends `permissionDecision`.
+
+**What leaves the Mac**
+- Only daily counts reach the Gateway.
+- Prompts, commands, paths, hosts, file contents and session ids stay on the Mac.
+- The remote URL embeds a token, so it is never stored.
+- `doctor` shows the policy, the guide hooks with Codex trust, today's counts and the recent local lines.
+
+Remove guide with `integrations remove --feature guide`. Without the Gateway's guide switch the hooks print and record
+nothing.
+
 ## 0.1.53: separate candidate change, file and payload limits
 
 ## 0.1.54: read only the source lines you need

package/dist/src/asks/commands.js

@@ -3,27 +3,61 @@ import { join } from "node:path";
 import { ASKS_FILE } from "./store.js";
 import { installIntegration, integrationStatus, removeIntegration, removeShimIfUnused } from "./integrations.js";
 import { APPS, isApp } from "./types.js";
+import { deleteGuideState } from "../guide/files.js";
+import { guideStatus, installGuide, removeGuide, removeGuideShimIfUnused } from "../guide/integrations.js";
 const NEXT_STEP = {
     claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-asks@skills-dir.",
     // /hooks is a command of the Codex CLI in a terminal only: the Codex app sends it to the model as text.
     codex: "Codex runs the four AI Gateway hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
         + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks. Until then the Slack message covers each ask.",
 };
-function errorCode(error) {
-    const code = error?.code;
-    if (typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code))
-        return code;
-    const message = error instanceof Error ? error.message.split(":")[0] : "";
-    return /^[A-Z0-9_]{1,64}$/.test(message) ? message : "INTEGRATION_FAILED";
+/** What an integrations command acts on (Work Item d38d60f9): asks, guide, or both; asks when no --feature is given. */
+export const FEATURES = ["asks", "guide"];
+const GUIDE_NEXT_STEP = {
+    claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-guide@skills-dir.",
+    codex: "Codex runs the two AI Gateway guide hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
+        + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks.",
+};
+const GUIDE_NOTICE = "Guide counts, per day: sessions, knowledge_search and other AI Gateway tool calls, KnowledgeBase reads and their bytes, "
+    + "and rule matches. Only these numbers reach the AI Gateway: prompts, commands, paths and file contents never leave this Mac.";
+const isFeatureFlag = (arg) => arg === "--feature" || arg.startsWith("--feature=");
+/** --feature asks|guide|asks,guide (or --feature=...): undefined when absent, null when malformed or given twice. */
+export function parseFeatures(argv) {
+    const index = argv.findIndex(isFeatureFlag);
+    if (index < 0)
+        return undefined;
+    if (argv.slice(index + 1).some(isFeatureFlag))
+        return null;
+    const value = argv[index] === "--feature" ? argv[index + 1] : argv[index].slice("--feature=".length);
+    const features = (value ?? "").split(",").map(feature => feature.trim()).filter(feature => feature !== "");
+    if (features.length === 0 || !features.every(feature => FEATURES.includes(feature)) || new Set(features).size !== features.length)
+        return null;
+    return features;
 }
-/** integrations status|install|remove [claude|codex]; null for anything else. */
+function withoutFeatureFlag(argv) {
+    const index = argv.findIndex(isFeatureFlag);
+    if (index < 0)
+        return argv;
+    return [...argv.slice(0, index), ...argv.slice(index + (argv[index] === "--feature" ? 2 : 1))];
+}
+/** integrations status|install|remove [claude|codex] [--feature ...]; null for anything else. features only when given. */
 export function parseIntegrationsArguments(argv) {
-    const [action, app, ...extra] = argv;
+    const features = parseFeatures(argv);
+    if (features === null)
+        return null;
+    const [action, app, ...extra] = withoutFeatureFlag(argv);
     if (extra.length > 0 || (action !== "status" && action !== "install" && action !== "remove"))
         return null;
     if (app !== undefined && !isApp(app))
         return null;
-    return { action, apps: app === undefined ? [...APPS] : [app] };
+    return { action, apps: app === undefined ? [...APPS] : [app], ...(features ? { features } : {}) };
+}
+function errorCode(error) {
+    const code = error?.code;
+    if (typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code))
+        return code;
+    const message = error instanceof Error ? error.message.split(":")[0] : "";
+    return /^[A-Z0-9_]{1,64}$/.test(message) ? message : "INTEGRATION_FAILED";
 }
 /** setup --integrations claude,codex (or --integrations=claude): undefined when absent, null when malformed. */
 export function parseSetupIntegrations(argv) {
@@ -61,6 +95,47 @@ export async function installIntegrations(apps, env, stateRoot) {
     }
     return results;
 }
+/** The guide state of one app; a status that cannot be read is reported with its error, never thrown. */
+export async function guideStatusOf(app, env, stateRoot, error) {
+    try {
+        return { ...await guideStatus(app, env, stateRoot), ...(error === undefined ? {} : { error }) };
+    }
+    catch (failure) {
+        return { app, state: "unreadable", path: "", error: error ?? errorCode(failure) };
+    }
+}
+async function attemptGuide(app, env, stateRoot, change) {
+    try {
+        return await change();
+    }
+    catch (error) {
+        return guideStatusOf(app, env, stateRoot, errorCode(error));
+    }
+}
+export async function installGuideIntegrations(apps, env, stateRoot) {
+    const results = [];
+    for (const app of apps) {
+        const result = await attemptGuide(app, env, stateRoot, () => installGuide(app, env, stateRoot));
+        results.push(result.error === undefined ? { ...result, action: GUIDE_NEXT_STEP[app], notice: GUIDE_NOTICE } : result);
+    }
+    return results;
+}
+/**
+ * uninstall: removes guide from both apps, then the guide shim and everything guide keeps on the Mac. Reports only the
+ * apps where something was removed, so an uninstall without guide prints exactly what it printed before.
+ */
+export async function removeGuideInstall(env, stateRoot) {
+    const results = [];
+    for (const app of APPS) {
+        const before = await guideStatusOf(app, env, stateRoot);
+        if (before.state === "not_installed")
+            continue;
+        results.push(await attemptGuide(app, env, stateRoot, () => removeGuide(app, env, stateRoot)));
+    }
+    await removeGuideShimIfUnused(env, stateRoot).catch(() => false);
+    await deleteGuideState(stateRoot);
+    return results;
+}
 /**
  * uninstall: removes both integrations, then the shim once nothing uses it, asks.json and the store's temporary files
  * that a crash left behind (asks.json.<pid>.<uuid>.tmp), which can hold raw session ids.
@@ -81,22 +156,40 @@ export async function removeAsksInstall(env, stateRoot) {
 export async function runIntegrationsCommand(argv, io) {
     const parsed = parseIntegrationsArguments(argv);
     if (parsed === null) {
-        io.stderr("Usage: mtec-ai-local-runner integrations status|install|remove [claude|codex]");
+        io.stderr("Usage: mtec-ai-local-runner integrations status|install|remove [claude|codex] [--feature asks|guide|asks,guide]");
         return 1;
     }
-    let results;
+    const features = parsed.features ?? ["asks"];
+    let results = [];
+    if (features.includes("asks")) {
+        if (parsed.action === "install") {
+            results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+        }
+        else if (parsed.action === "remove") {
+            for (const app of parsed.apps)
+                results.push(await attempt(app, io.env, io.stateRoot, () => removeIntegration(app, io.env, io.stateRoot)));
+            await removeShimIfUnused(io.env, io.stateRoot).catch(() => false);
+        }
+        else {
+            results = await Promise.all(parsed.apps.map(app => statusOf(app, io.env, io.stateRoot)));
+        }
+    }
+    if (!features.includes("guide")) {
+        io.stdout(JSON.stringify({ integrations: results }));
+        return results.some(result => result.error !== undefined) ? 1 : 0;
+    }
+    let guide = [];
     if (parsed.action === "install") {
-        results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+        guide = await installGuideIntegrations(parsed.apps, io.env, io.stateRoot);
     }
     else if (parsed.action === "remove") {
-        results = [];
         for (const app of parsed.apps)
-            results.push(await attempt(app, io.env, io.stateRoot, () => removeIntegration(app, io.env, io.stateRoot)));
-        await removeShimIfUnused(io.env, io.stateRoot).catch(() => false);
+            guide.push(await attemptGuide(app, io.env, io.stateRoot, () => removeGuide(app, io.env, io.stateRoot)));
+        await removeGuideShimIfUnused(io.env, io.stateRoot).catch(() => false);
     }
     else {
-        results = await Promise.all(parsed.apps.map(app => statusOf(app, io.env, io.stateRoot)));
+        guide = await Promise.all(parsed.apps.map(app => guideStatusOf(app, io.env, io.stateRoot)));
     }
-    io.stdout(JSON.stringify({ integrations: results }));
-    return results.some(result => result.error !== undefined) ? 1 : 0;
+    io.stdout(JSON.stringify({ integrations: results, guide }));
+    return [...results, ...guide].some(result => result.error !== undefined) ? 1 : 0;
 }

package/dist/src/asks/hook-client.js

@@ -56,6 +56,32 @@ export function isHumanSession(app, env, _input, stateRoot) {
         return attended === "1";
     return INTERACTIVE_ENTRYPOINTS.has(env.CLAUDE_CODE_ENTRYPOINT ?? "");
 }
+/** The reminders a client app puts in front of what was submitted, typed or not. */
+const LEADING_REMINDERS = /^\s*(?:<system-reminder>[\s\S]*?<\/system-reminder>\s*)+/;
+/**
+ * How a turn nobody typed begins (Work Decision cc8817f9), as the 2026-10-26 transcripts recorded them. Claude Code runs
+ * UserPromptSubmit for these turns as well, and its hook input says nothing of where a prompt came from.
+ * - A Claude asyncRewake wake and a background task: a task notification.
+ * - The app's report of a side session's turn, and a message from another session.
+ * - A side session's first brief, written by the session that started it.
+ * - The summary that continues a compacted conversation, and an interruption marker.
+ * - This runner's own lines.
+ */
+const NOT_TYPED_PREFIXES = [
+    "<task-notification>", "<side-sessions-event>", "<cross-session-message", "<agent-message", "Another Claude session sent a message:",
+    "Background (from the session that started this one):", "This session is being continued from a previous conversation",
+    "[Request interrupted by user", "AI Gateway:",
+];
+/**
+ * True when a person typed this prompt. Only the answer leaves this client, never the text. A prompt that is not a
+ * string counts as typed, as every prompt did before this rule.
+ */
+export function isHumanPrompt(prompt) {
+    if (typeof prompt !== "string")
+        return true;
+    const rest = prompt.replace(LEADING_REMINDERS, "").trimStart();
+    return rest !== "" && !NOT_TYPED_PREFIXES.some(prefix => rest.startsWith(prefix));
+}
 /** Same rule as defaultStateRootFromEnv in src/config.ts, repeated so this client loads nothing else. */
 function stateRootFrom(env) {
     return env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "mtec-ai-local-runner") : join(env.HOME ?? "", ".local", "state", "mtec-ai-local-runner");
@@ -107,7 +133,7 @@ function parseRecord(raw) {
     }
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field, the prompt included, is ignored. */
+/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field is ignored; the prompt is only classified (isHumanPrompt). */
 function hookFields(input) {
     const { session_id: sessionId, cwd, stop_hook_active: stopHookActive } = input;
     if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
@@ -194,9 +220,10 @@ export async function runHookClient(argv, io) {
             io.stderr(text);
             return 2;
         }
-        const request = args.event === "stop"
-            ? { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd, stop_hook_active: input.stopHookActive }
-            : { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const base = { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const request = args.event === "stop" ? { ...base, stop_hook_active: input.stopHookActive }
+            : args.event === "prompt" ? { ...base, human: isHumanPrompt(record.prompt) }
+                : base;
         const text = await converse(socketPath, encodeLine(request), hubTimeoutMs, hubTimeoutMs, line => ({ done: true, value: parseEventResponse(line)?.text ?? null }));
         if (text === null || text === "")
             return 0;

package/dist/src/asks/hub-protocol.js

@@ -5,7 +5,9 @@ import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
  * may import nothing but ./types.js.
  *
  * Client to hub, one line, then the client waits without closing its side:
- *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"prompt"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"prompt","session_id":…,"cwd":…,"human":true|false}
+ *                                                 (a client from before the flag sends no "human"; that prompt counts as typed)
  *   {"v":1,"op":"event","app":"codex","event":"stop","session_id":…,"cwd":…,"stop_hook_active":false}
  *   {"v":1,"op":"watch","app":"claude","session_id":…,"cwd":…}        (the Claude Stop watcher)
  *   {"v":1,"op":"status"}                                             (doctor)
@@ -68,6 +70,11 @@ export function parseHubRequest(line) {
             return null;
         return { v: 1, op: "event", app: "codex", event: "stop", session_id: value.session_id, cwd: value.cwd, stop_hook_active: value.stop_hook_active };
     }
+    if (value.event === "prompt" && Object.keys(value).length === 7) {
+        if (typeof value.human !== "boolean")
+            return null;
+        return { v: 1, op: "event", app: value.app, event: "prompt", session_id: value.session_id, cwd: value.cwd, human: value.human };
+    }
     if (Object.keys(value).length !== 6)
         return null;
     return { v: 1, op: "event", app: value.app, event: value.event, session_id: value.session_id, cwd: value.cwd };

package/dist/src/asks/inbox.js

@@ -83,7 +83,7 @@ export class AskInbox {
                     answer(null);
                     return;
                 }
-                const context = { app: request.app, sessionId: request.session_id, cwd: request.cwd, now: this.now() };
+                const context = { app: request.app, sessionId: request.session_id, cwd: request.cwd, now: this.now(), human: request.human !== false };
                 let text = null;
                 if (request.event === "session-start")
                     text = renderOutput(sessionStarted(this.state, context), { sessionId: request.session_id });

package/dist/src/asks/messenger.js

@@ -12,6 +12,7 @@ import { abortableDelay } from "../transport/abortable-delay.js";
 import { sideLoops, tickingHeartbeat } from "../transport/side-loops.js";
 import { packageVersion } from "../package-version.js";
 import { AskRuntime, withAsks } from "./runtime.js";
+import { GuideRuntime, withGuide } from "../guide/runtime.js";
 /*
  * Messenger mode (Work Item e1c08b33, spec section 8.1). Setup chose it because no executor is admitted on
  * this Mac. The daemon runs the push transport only (Work Item 25d8ea74): there is no jobs loop, no adapter probe,
@@ -93,6 +94,8 @@ export async function buildMessengerDaemon(input) {
     const gateway = new McpGatewayClient({ mcpUrl: input.gatewayMcpUrl, tokenProvider: input.tokenProvider, runnerId: input.runnerId, fetchFn: input.fetchFn });
     const asks = new AskRuntime({ stateRoot: input.stateRoot, env: input.env, now: input.now, log, installedApps: input.installedApps,
         report: (deliveryId, report, signal) => gateway.reportAskDelivery({ deliveryId, ...report }, signal) });
+    const guide = new GuideRuntime({ stateRoot: input.stateRoot, env: input.env, now: input.now, log,
+        report: (day, signal) => gateway.reportGuidance(day, signal) });
     const heartbeat = messengerHeartbeat(async (signal) => {
         let sessionOpen;
         // A detection error only leaves session_open out; the Gateway keeps what it stored.
@@ -103,16 +106,18 @@ export async function buildMessengerDaemon(input) {
             sessionOpen = undefined;
         }
         const askInbox = await asks.advertisement();
+        const guidance = await guide.advertisement();
         await gateway.heartbeatLocalRunner({
             deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
             displayName: runnerDisplayName(), packageVersion: packageVersion(), capabilities: [], mode: "messenger",
             // Without an integration, session_open still goes out (clients only): the Gateway keeps the last one it stored, and would keep long-polling for asks.
             ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
+            ...(guidance ? { guidance } : {}),
         }, signal);
         // Without session_open the Gateway keeps its stored ask_inbox, which may be stale: send again, backing off.
         return sessionOpen !== undefined;
     }, { now: input.now, reportError: code => log({ event: "messenger_heartbeat_failed", code }),
-        advertised: async () => JSON.stringify(await asks.advertisement() ?? null) });
+        advertised: async () => JSON.stringify([await asks.advertisement() ?? null, await guide.advertisement() ?? null]) });
     const opener = new SessionOpener({ home });
     const stopping = new AbortController();
     const closureAcks = new PendingClosureAcks();
@@ -122,6 +127,7 @@ export async function buildMessengerDaemon(input) {
             await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
                 failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
         },
+        guide,
         asks,
         closureAcks,
         delay: abortableDelay,
@@ -133,7 +139,7 @@ export async function buildMessengerDaemon(input) {
         sync: async (reason, signal) => {
             const acknowledged = closureAcks.take();
             try {
-                return await gateway.syncRunner({ adapterVersions: {}, reason, acknowledgedClosureIds: acknowledged }, signal);
+                return await gateway.syncRunner({ adapterVersions: {}, reason, acknowledgedClosureIds: acknowledged, guidancePolicyVersion: await guide.policyVersion() }, signal);
             }
             catch (error) {
                 closureAcks.restore(acknowledged);
@@ -156,7 +162,7 @@ export async function buildMessengerDaemon(input) {
         state: { load: async () => null },
         reconcile: async () => undefined,
         poller: idleJobPoller(),
-        sessionOpens: withAsks(asks, sessionOpens),
+        sessionOpens: withGuide(guide, withAsks(asks, sessionOpens)),
     });
     return { daemon, close: async () => { daemon.stop(); } };
 }

package/dist/src/asks/routing.js

@@ -19,6 +19,12 @@ export const MAX_ITEMS_PER_OUTPUT = 5;
 export const OPEN_PENDING_MS = 15 * 60 * 1000;
 /** At most 3 sessions opened per Mac in any hour. */
 export const OPEN_LIMIT = 3;
+/**
+ * A prompt this soon after a wake or a stop show does not count as seen (Work Decision cc8817f9). Claude submits the
+ * woken turn itself within a few seconds, and a person needs longer to read the ask and type. An early typed prompt
+ * leaves the item shown: the next one counts, or the Gateway's Slack fallback covers it.
+ */
+export const SEEN_AFTER_CONTINUATION_MS = 10_000;
 export function hashSessionId(sessionId) {
     return createHash("sha256").update(sessionId, "utf8").digest("hex");
 }
@@ -29,8 +35,10 @@ export function isLive(session, now) {
 export function humanPromptWithin(session, now) {
     return session.lastPromptAt !== null && now - session.lastPromptAt <= WAKE_WINDOW_MS;
 }
+/** A turn started by a typed prompt or by one nobody typed has not ended yet. */
 export function turnInProgress(session) {
-    return session.lastPromptAt !== null && (session.lastTurnEndAt === null || session.lastPromptAt > session.lastTurnEndAt);
+    const started = Math.max(session.lastPromptAt ?? -1, session.lastTurnStartAt ?? -1);
+    return started >= 0 && (session.lastTurnEndAt === null || started > session.lastTurnEndAt);
 }
 export function wakesLeft(session, now) {
     return WAKE_LIMIT - session.wakes.filter(at => now - at < WAKE_PERIOD_MS).length;
@@ -64,7 +72,8 @@ export function chooseSession(item, state, now) {
  * Where a delivery that is not shown yet goes now:
  * - no live session, or the chosen one had no human prompt in 30 minutes: a notification, then the next
  *   SessionStart or prompt in any session;
- * - the chosen session is in a turn: pinned there, shown at its turn end or next prompt;
+ * - the chosen session is in a turn: pinned there, shown at its turn end or at the next prompt in any session that
+ *   becomes the chosen one by that prompt (see promptSubmitted);
  * - an idle Claude session whose Stop watcher waits, under its hourly limit: woken now;
  * - otherwise (an idle Codex session, no watcher, or the limit reached): a notification.
  */
@@ -168,13 +177,30 @@ export function sessionStarted(state, context) {
         markShown(item, key, context.app, "session_start", context.now);
     return output;
 }
-/** UserPromptSubmit: earlier items shown in this session become seen; waiting items are shown and seen at once. */
+/**
+ * UserPromptSubmit. A prompt nobody typed only starts a turn: it shows nothing, counts nothing as seen and is not a human
+ * prompt for routing (Work Decision cc8817f9).
+ *
+ * A typed prompt makes earlier items shown in this session seen, except those a wake or a stop showed under
+ * SEEN_AFTER_CONTINUATION_MS ago. Waiting items are shown and seen at once. So is an item pinned to another session that
+ * this prompt makes the chosen session for it: the person just typed here, while that session is still in its turn.
+ * Without this the next plan pinned the item here to wait for this turn's end, and a prompt elsewhere could move it on
+ * again before then (live test 2026-10-26). An answer that names a live session stays there, because the session that
+ * asked is still chosen first.
+ */
 export function promptSubmitted(state, context) {
     const { key, session } = touch(state, context);
+    if (context.human === false) {
+        session.lastTurnStartAt = context.now;
+        return { items: [], more: [] };
+    }
     session.lastPromptAt = context.now;
-    for (const item of itemsWhere(state, item => item.phase === "shown" && item.sessionKey === key))
+    const settled = (item) => (item.shownVia !== "rewake" && item.shownVia !== "stop")
+        || item.shownAt === null || context.now - item.shownAt >= SEEN_AFTER_CONTINUATION_MS;
+    for (const item of itemsWhere(state, item => item.phase === "shown" && item.sessionKey === key && settled(item)))
         markSeen(item, context.app, context.now);
-    const output = selectForOutput(dueFor(state, key));
+    const takenOver = itemsWhere(state, item => item.phase === "pinned" && item.sessionKey !== key && chooseSession(item, state, context.now) === key);
+    const output = selectForOutput([...dueFor(state, key), ...takenOver]);
     for (const item of everyItem(output)) {
         markShown(item, key, context.app, "prompt", context.now);
         markSeen(item, context.app, context.now);

package/dist/src/asks/shim.js

@@ -8,12 +8,11 @@ import { fileURLToPath } from "node:url";
  * rewrites it at start so it follows the running release.
  */
 export const SHIM_FILE = join("bin", "gateway-hook");
+/** The guide hooks' own stable entry point (Work Item d38d60f9): it execs dist/src/guide/hook-client.js. */
+export const GUIDE_SHIM_FILE = join("bin", "gateway-guide-hook");
 // Paths go into single quotes in the shim and double quotes in hook commands; only characters that stay literal in
 // both are allowed (the same set as the PreToolUse hook command), so no quote, $, backquote or backslash.
 const SAFE_PATH = /^[A-Za-z0-9._/:@+~,=% -]+$/;
-export function shimPath(stateRoot) {
-    return join(stateRoot, SHIM_FILE);
-}
 /** The hook client installed next to this module (dist/src/asks/hook-client.js in the package). */
 export function hookClientScript() {
     return fileURLToPath(new URL("./hook-client.js", import.meta.url));
@@ -25,9 +24,16 @@ function safePath(label, path) {
     }
     return path;
 }
-/** The command line in every installed hook. It names only the shim, the app and the event. */
+export function shimPath(stateRoot, file = SHIM_FILE) {
+    return join(stateRoot, file);
+}
+/** The command line of an installed hook: the quoted shim, then the words given (an app and an event). */
+export function shimCommand(stateRoot, file, args) {
+    return `"${safePath("shim", shimPath(stateRoot, file))}" ${args.join(" ")}`;
+}
+/** The command line in every installed asks hook. It names only the shim, the app and the event. */
 export function hookCommand(stateRoot, app, event) {
-    return `"${safePath("shim", shimPath(stateRoot))}" ${app} ${event}`;
+    return shimCommand(stateRoot, SHIM_FILE, [app, event]);
 }
 export function renderShim(input) {
     const node = safePath("Node executable", input.nodePath);
@@ -35,7 +41,7 @@ export function renderShim(input) {
     const stateRoot = safePath("state root", input.stateRoot);
     return [
         "#!/bin/sh",
-        "# Written by mtech-ai-local-runner for AI Gateway asks. The runner rewrites this file; do not edit it.",
+        `# Written by mtech-ai-local-runner for AI Gateway ${input.feature ?? "asks"}. The runner rewrites this file; do not edit it.`,
         `node='${node}'`,
         `client='${client}'`,
         "# A runner release that is gone must never disturb a session: print nothing and succeed.",
@@ -46,8 +52,9 @@ export function renderShim(input) {
 }
 /** Writes the shim atomically with mode 0755 for this release. Returns whether its content changed. */
 export async function writeShim(input) {
-    const path = shimPath(input.stateRoot);
-    const content = renderShim({ nodePath: input.nodePath ?? process.execPath, clientPath: input.clientPath ?? hookClientScript(), stateRoot: input.stateRoot });
+    const path = shimPath(input.stateRoot, input.file);
+    const content = renderShim({ nodePath: input.nodePath ?? process.execPath, clientPath: input.clientPath ?? hookClientScript(),
+        stateRoot: input.stateRoot, feature: input.feature });
     if (await readFile(path, "utf8").catch(() => null) === content)
         return { path, changed: false };
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
@@ -66,13 +73,13 @@ export async function writeShim(input) {
 /** Points an existing shim at the running release. It never creates one: installing an integration does. */
 export async function refreshShim(input) {
     try {
-        await access(shimPath(input.stateRoot));
+        await access(shimPath(input.stateRoot, input.file));
     }
     catch {
         return false;
     }
     return (await writeShim(input)).changed;
 }
-export async function removeShim(stateRoot) {
-    await rm(shimPath(stateRoot), { force: true });
+export async function removeShim(stateRoot, file = SHIM_FILE) {
+    await rm(shimPath(stateRoot, file), { force: true });
 }

package/dist/src/asks/store.js

@@ -100,7 +100,11 @@ function normalizeSession(key, value) {
         return null;
     if (!Array.isArray(v.wakes) || !v.wakes.every(isTime))
         return null;
+    // Stored before Work Decision cc8817f9 a session has no turn start; one that is not a time is dropped with the session.
+    if (v.lastTurnStartAt !== undefined && !isTime(v.lastTurnStartAt))
+        return null;
     return { app: v.app, sessionId: v.sessionId, cwd: v.cwd, startedAt: v.startedAt, lastEventAt: v.lastEventAt, lastPromptAt: v.lastPromptAt,
+        ...(v.lastTurnStartAt === undefined ? {} : { lastTurnStartAt: v.lastTurnStartAt }),
         lastTurnEndAt: v.lastTurnEndAt, endedAt: v.endedAt, wakes: [...v.wakes] };
 }
 /**

package/dist/src/cli.js

@@ -31,8 +31,9 @@ import { verifyPackagedHook } from "./safety/hook-command.js";
 import { access, mkdir, rm } from "node:fs/promises";
 import { buildMessengerDaemon } from "./asks/messenger.js";
 import { runHookClient } from "./asks/hook-client.js";
-import { installIntegrations, parseSetupIntegrations, removeAsksInstall, runIntegrationsCommand } from "./asks/commands.js";
+import { installGuideIntegrations, installIntegrations, parseFeatures, parseSetupIntegrations, removeAsksInstall, removeGuideInstall, runIntegrationsCommand } from "./asks/commands.js";
 import { asksDoctorReport } from "./asks/doctor.js";
+import { guideDoctorReport, guideReportShown } from "./guide/doctor.js";
 function hookAction(result) {
     return result.reason === "invalid_command"
         ? "Run the runner with a Node executable and package path outside the workspace, without quotes, $, backquotes or backslashes, then rerun doctor."
@@ -199,6 +200,9 @@ export async function main(argv, env, io = {}) {
                 const requestedIntegrations = parseSetupIntegrations(argv.slice(1));
                 if (requestedIntegrations === null)
                     throw new Error("--integrations takes claude, codex or claude,codex");
+                const requestedFeatures = parseFeatures(argv.slice(1));
+                if (requestedFeatures === null)
+                    throw new Error("--feature takes asks, guide or asks,guide");
                 const existing = await existingRunnerMode(config.stateRoot, localStore);
                 const detected = await (io.discoverAdapters?.() ?? discoverEmployeeAdapters(env));
                 // A Mac already set up as a full runner is never turned into a messenger: it fails as before, untouched.
@@ -239,11 +243,13 @@ export async function main(argv, env, io = {}) {
                 await localStore.save({ schemaVersion: 1, gatewayMcpUrl: config.gatewayMcpUrl, runnerId: registered.runner.id, workspaceRoot: config.workspaceRoot, concurrency: 1, ...(mode === "messenger" ? { mode } : {}) });
                 // Only the apps named with --integrations: setup never asks. Before the daemon starts, so its first heartbeat
                 // already advertises what is installed.
-                const integrations = await installIntegrations(requestedIntegrations ?? [], env, config.stateRoot);
+                const features = requestedFeatures ?? ["asks"];
+                const integrations = features.includes("asks") ? await installIntegrations(requestedIntegrations ?? [], env, config.stateRoot) : [];
+                const guide = features.includes("guide") ? await installGuideIntegrations(requestedIntegrations ?? [], env, config.stateRoot) : undefined;
                 await launchd.install(process.argv[1], config.stateRoot);
                 stdout(JSON.stringify(mode === "full"
-                    ? { configured: true, mode, runnerId: registered.runner.id, adapters, integrations }
-                    : { configured: true, mode, runnerId: registered.runner.id, adapters: adapterDiagnosticsWithRemedies(detected), integrations,
+                    ? { configured: true, mode, runnerId: registered.runner.id, adapters, integrations, ...(guide ? { guide } : {}) }
+                    : { configured: true, mode, runnerId: registered.runner.id, adapters: adapterDiagnosticsWithRemedies(detected), integrations, ...(guide ? { guide } : {}),
                         action: "No executor is admitted on this Mac, so the runner is set up as a messenger: it delivers AI Gateway asks and opens sessions, and runs no jobs. Resolve the adapter diagnostics, then rerun setup to run jobs." }));
                 return 0;
             }
@@ -251,8 +257,9 @@ export async function main(argv, env, io = {}) {
             if (config.mode === "uninstall") {
                 await launchd.uninstall();
                 const integrations = await removeAsksInstall(env, config.stateRoot);
+                const guide = await removeGuideInstall(env, config.stateRoot);
                 await rm(join(config.stateRoot, "config.json"), { force: true });
-                stdout(JSON.stringify({ uninstalled: true, integrations }));
+                stdout(JSON.stringify({ uninstalled: true, integrations, ...(guide.length > 0 ? { guide } : {}) }));
                 return 0;
             }
             const doctorAdapters = config.mode === "doctor" ? adapterDiagnosticsWithRemedies(await (io.discoverAdapters?.() ?? discoverEmployeeAdapters(env))) : undefined;
@@ -313,6 +320,7 @@ export async function main(argv, env, io = {}) {
                 // A messenger runs no executor, so neither an adapter nor the PreToolUse self-test is required of it.
                 const hookCheck = messenger ? Promise.resolve(null) : hookSelfTest(local.workspaceRoot);
                 const asksCheck = asksDoctorReport({ stateRoot: config.stateRoot, env, mode: runnerMode(local), run: io.claudePluginList });
+                const guideCheck = guideDoctorReport({ stateRoot: config.stateRoot, env });
                 // Refresh rotating credentials once before the Gateway client asks for a token.
                 const [oauth] = await Promise.allSettled([tokenProvider.getToken()]);
                 const [gateway] = oauth.status === "fulfilled"
@@ -321,11 +329,12 @@ export async function main(argv, env, io = {}) {
                 const [service, workspace] = await localChecks;
                 const hook = await hookCheck;
                 const asks = await asksCheck;
+                const guide = await guideCheck;
                 const checks = [oauth, gateway, service, workspace];
                 const loaded = service.status === "fulfilled" && service.value.loaded;
                 const ok = checks.every(check => check.status === "fulfilled") && loaded && (hook === null || (hasUsableAdapter(adapters) && hook.enforcing));
                 stdout(JSON.stringify({ ok, configured: true, adapters, checks: { runner_registration: true, oauth: oauth.status === "fulfilled", gateway: gateway.status === "fulfilled", workspace: workspace.status === "fulfilled", launchd: loaded, ...(hook === null ? {} : { hook: hook.enforcing }) },
-                    hook: hook === null ? { status: "not_required", reason: "messenger_mode" } : hookReport(hook), ...asks, ...(gateway.status === "fulfilled" ? { runner: gateway.value } : {}), ...(service.status === "fulfilled" ? { launchd: service.value } : {}) }));
+                    hook: hook === null ? { status: "not_required", reason: "messenger_mode" } : hookReport(hook), ...asks, ...(guideReportShown(guide) ? { guide } : {}), ...(gateway.status === "fulfilled" ? { runner: gateway.value } : {}), ...(service.status === "fulfilled" ? { launchd: service.value } : {}) }));
                 return ok ? 0 : 1;
             }
             if (config.mode === 'manual-codex') {