mtech-ai-local-runner 0.1.104 → 0.1.106

package/README.md

@@ -354,11 +354,20 @@ apart. Codex jobs run with `features.hooks=false`, so they run no hook at all.
 
 An ask is shown at a session start, at the next prompt (where it also counts as seen), at a turn end, or by waking an
 idle Claude session through an `asyncRewake` Stop watcher. An ask shown at a session start, at a turn end or by a wake
-counts as seen at the next prompt in that same session. A session is woken only within 30 minutes of a human prompt,
-and at most 6 times an hour. With no such session the ask becomes one macOS notification, which gives up after 3
+counts as seen at the next prompt in that same session. Ordinary and acceptance deliveries require a human prompt
+within 30 minutes to wake a session. An exact investigation approval notice can wake its live bound Claude session
+without a recent prompt, but still needs its own watcher and the 6-wakes-per-hour allowance. With no such session the ask becomes one macOS notification, which gives up after 3
 seconds and logs only an error code, and the ask waits for the next session start or prompt. Hook text is fixed and
 carries validated ids only; the AI reads the ask itself with the Gateway show tools, which mark its text as untrusted.
 
+Unreleased source adds a Claude SessionStart `asyncRewake` watcher so a resumed conversation can receive that exact
+investigation notice without a typed prompt. Synchronous SessionStart leaves those notices pending for the watcher,
+regardless of hook arrival order. Neither registration nor the watcher invents a human prompt or a turn end; a busy
+turn waits for its real Stop. Ordinary requests, acceptance delivery and Codex hooks retain their existing behavior.
+Runner 0.1.105 does not include this fix. A separately reviewed package and installation of its updated Claude hooks
+are required; package publication alone does not refresh an already open conversation. The recipient must still
+check current Gateway authorization before accessing the pinned files or recording its result.
+
 An ask or answer the runner puts into a session on its own, by a wake or at a turn end, also gets one macOS
 notification naming that app and session ("It is in your Claude session in api-cloud-service-ai-gateway (last typed
 17:39)."), since the person may be looking elsewhere (Work Item 643dc395). Hooks carry no session title, so the

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

@@ -154,7 +154,7 @@ function parseArguments(argv, env) {
             return null;
     }
     const [app, event, ...extra] = rest;
-    if (extra.length > 0 || !isApp(app) || !isHookEvent(event))
+    if (extra.length > 0 || !isApp(app) || (!isHookEvent(event) && !(app === "claude" && event === "start-watch")))
         return null;
     return { stateRoot, app, event };
 }
@@ -259,15 +259,18 @@ export async function runHookClient(argv, io) {
         const input = record === null ? null : hookFields(record);
         if (record === null || input === null)
             return 0;
+        if (args.event === "start-watch" && record.hook_event_name !== "SessionStart")
+            return 0;
         // Before the first byte goes to the hub: a session nobody attends is not registered, shown an ask or counted as seen.
         const lineage = args.app === "claude" ? (io.processLineage ?? readProcessLineage)() : null;
         if (!isHumanSession(args.app, io.env, record, args.stateRoot, lineage))
             return 0;
         const socketPath = join(args.stateRoot, HUB_SOCKET);
         const hubTimeoutMs = io.hubTimeoutMs ?? HUB_TIMEOUT_MS;
-        if (args.app === "claude" && args.event === "stop") {
+        if (args.app === "claude" && (args.event === "stop" || args.event === "start-watch")) {
             // The asyncRewake watcher: exit 2 with the text on stderr wakes Claude, even when the session is idle.
-            const text = await converse(socketPath, encodeLine({ v: 1, op: "watch", app: "claude", session_id: input.sessionId, cwd: input.cwd }), hubTimeoutMs, io.watchLimitMs ?? WATCH_LIMIT_MS, (line, first) => {
+            const text = await converse(socketPath, encodeLine({ v: 1, op: "watch", app: "claude", session_id: input.sessionId, cwd: input.cwd,
+                ...(args.event === "start-watch" ? { source: "session-start" } : {}) }), hubTimeoutMs, io.watchLimitMs ?? WATCH_LIMIT_MS, (line, first) => {
                 const message = parseWatchMessage(line);
                 if (message?.type === "wake")
                     return { done: true, value: message.text };

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

@@ -10,6 +10,7 @@ import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
  *                                                 (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":"watch","app":"claude","session_id":…,"cwd":…,"source":"session-start"} (resume watcher)
  *   {"v":1,"op":"status"}                                             (doctor)
  * Hub to client:
  *   event:  {"v":1,"ok":true,"text":"…"|null}, then the hub closes the connection
@@ -58,9 +59,11 @@ export function parseHubRequest(line) {
     if (typeof value.cwd !== "string" || value.cwd.length > MAX_CWD_LENGTH)
         return null;
     if (value.op === "watch") {
-        if (value.app !== "claude" || Object.keys(value).length !== 5)
+        if (value.app !== "claude" || Object.keys(value).length !== (value.source === undefined ? 5 : 6)
+            || (value.source !== undefined && value.source !== "session-start"))
             return null;
-        return { v: 1, op: "watch", app: "claude", session_id: value.session_id, cwd: value.cwd };
+        return { v: 1, op: "watch", app: "claude", session_id: value.session_id, cwd: value.cwd,
+            ...(value.source === "session-start" ? { source: "session-start" } : {}) };
     }
     if (value.op !== "event" || !isApp(value.app) || !isHookEvent(value.event))
         return null;

package/dist/src/asks/inbox.js

@@ -1,5 +1,5 @@
 import { emptyAskState, pruneAskState, sessionKey } from "./store.js";
-import { addDeliveries, hashSessionId, humanPromptWithin, claimOpen, claimShownNotifications, closeDeliveries, confirmNotified, confirmOpened, confirmWake, isLive, openApp, planRoutes, preferredApp, promptSubmitted, releaseOpen, sessionEnded, sessionStarted, turnEnded, } from "./routing.js";
+import { addDeliveries, hashSessionId, claimOpen, claimShownNotifications, closeDeliveries, confirmNotified, confirmOpened, confirmWake, isLive, openApp, planRoutes, preferredApp, promptSubmitted, releaseOpen, sessionEnded, sessionStarted, turnEnded, } from "./routing.js";
 import { MAX_TARGET_HASHES, droppableDeliveryId, parseAskDelivery } from "./types.js";
 import { renderOutput } from "./templates.js";
 import { PRESENCE_RECHECK_MS } from "./presence.js";
@@ -77,11 +77,14 @@ export class AskInbox {
         const session = key === null ? undefined : this.state.sessions[key];
         return session === undefined ? undefined : sessionPlace(session.cwd, session.lastPromptAt);
     }
-    /** The app of the session with the most recent typed prompt, for an alert's Open button (Work Item 643dc395). */
+    /**
+     * Readiness names live attended sessions. The Gateway checks signed approval and exact identity;
+     * ordinary and acceptance delivery still apply their human-prompt age rule when routing locally.
+     */
     acceptanceSessionHashes() {
         const now = this.now();
         return Object.values(this.state.sessions)
-            .filter(session => isLive(session, now) && humanPromptWithin(session, now))
+            .filter(session => isLive(session, now))
             .sort((left, right) => right.lastEventAt - left.lastEventAt)
             .slice(0, MAX_TARGET_HASHES)
             .map(session => hashSessionId(session.sessionId));
@@ -120,9 +123,10 @@ export class AskInbox {
         });
     }
     /**
-     * A Claude Stop watcher. A Claude turn end is always a watch, so registering one is the session's turn end: it runs
+     * A Claude Stop or SessionStart watcher. A real turn end runs
      * turnEnded(), which shows what is already pinned to the session (via stop) and marks the session idle. Without that
      * the session would still count as in a turn, and the wake branch of the routing rules could never be reached.
+     * A SessionStart watcher only waits; it cannot mark an interrupted or running turn ended.
      * What is not pinned makes the watcher wait, replacing any older watcher of the same session.
      */
     watch(request, watcher) {
@@ -133,7 +137,8 @@ export class AskInbox {
             const key = sessionKey("claude", request.session_id);
             this.release(key, "replaced");
             // Claude's own loop guard is the hourly wake limit; stop_hook_active belongs to Stop decisions, not to a rewake.
-            const text = renderOutput(turnEnded(this.state, { app: "claude", sessionId: request.session_id, cwd: request.cwd, now: this.now() }, { stopHookActive: false }));
+            const text = request.source === "session-start" ? null
+                : renderOutput(turnEnded(this.state, { app: "claude", sessionId: request.session_id, cwd: request.cwd, now: this.now() }, { stopHookActive: false }));
             if (text !== null) {
                 watcher.wake(text);
             }

package/dist/src/asks/integrations.js

@@ -67,7 +67,7 @@ export function claudePluginManifest() {
 export function claudeHooksFile(stateRoot) {
     const handler = (event, extra = {}) => ({ type: "command", command: hookCommand(stateRoot, "claude", event), ...extra });
     return { description: CLAUDE_HOOKS_DESCRIPTION, hooks: {
-            SessionStart: [{ hooks: [handler("session-start", { timeout: 10 })] }],
+            SessionStart: [{ hooks: [handler("session-start", { timeout: 10 }), handler("start-watch", { asyncRewake: true, timeout: 3600 })] }],
             UserPromptSubmit: [{ hooks: [handler("prompt", { timeout: 10 })] }],
             Stop: [{ hooks: [handler("stop", { asyncRewake: true, timeout: 3600 })] }],
             SessionEnd: [{ hooks: [handler("session-end")] }],

package/dist/src/asks/notifier.js

@@ -9,12 +9,14 @@ const ASK_LEAD = {
     review: "AI Gateway: a colleague asked you for a review.",
     request: "AI Gateway: a colleague asked you for an answer.",
     acceptance: "AI Gateway: a request acceptance is available in its bound conversation.",
+    investigation: "AI Gateway: an investigation approval is available in its bound conversation.",
 };
 const ANSWER_LEAD = {
     decision: "AI Gateway: your decision request has been answered.",
     review: "AI Gateway: your review request has been answered.",
     request: "AI Gateway: your work request has been answered.",
     acceptance: "AI Gateway: a request acceptance is available in its bound conversation.",
+    investigation: "AI Gateway: an investigation approval is available in its bound conversation.",
 };
 const APP_NAME = { claude: "Claude", codex: "Codex" };
 /** Sent together with an open (open-session design section 5): the session is already there, in this app. */

package/dist/src/asks/routing.js

@@ -1,3 +1,4 @@
+import { isRecipientApproval } from "./types.js";
 import { createHash } from "node:crypto";
 import { OPEN_PERIOD_MS, SESSION_TTL_MS, WAKE_PERIOD_MS, sessionKey } from "./store.js";
 import { LOWER_UUID } from "./types.js";
@@ -6,7 +7,7 @@ import { LOWER_UUID } from "./types.js";
  * Every function here works on the in-memory AskState and does no I/O, so the rules are tested directly.
  * The AI's own actions never count as seen: only hook events the runner observes move a delivery forward.
  */
-/** A session is woken, or a delivery pinned to it, only after a human prompt within the last 30 minutes. */
+/** Ordinary and acceptance deliveries require a human prompt within the last 30 minutes. */
 export const WAKE_WINDOW_MS = 30 * 60 * 1000;
 /** At most 6 wakes per session per hour (Claude asyncRewake exits and Codex Stop continuations). */
 export const WAKE_LIMIT = 6;
@@ -122,6 +123,8 @@ export function chooseSession(item, state, now) {
  *   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.
+ * An exact investigation notice already names a signed approved scope, so its own live session can
+ * receive it without a recent human prompt. Its watcher and hourly wake limit are still required.
  * An answer whose asking session is live is pinned or woken there by the same rules, and otherwise held there: it waits
  * for that session, with a notification that says so, and no session is opened for it (Work Decision 8562d191).
  */
@@ -131,11 +134,12 @@ export function routeItem(item, state, now, watching) {
     const session = key === null ? undefined : state.sessions[key];
     if (key === null || session === undefined)
         return { action: "notify" };
-    if (asking === null && !humanPromptWithin(session, now))
+    const approvedInvestigation = item.subjectType === "investigation" && item.routingPolicy === "exact";
+    if (asking === null && !approvedInvestigation && !humanPromptWithin(session, now))
         return { action: "notify" };
     if (turnInProgress(session))
         return { action: "pin", sessionKey: key };
-    if (session.app === "claude" && humanPromptWithin(session, now) && watching.has(key) && wakesLeft(session, now) > 0)
+    if (session.app === "claude" && (approvedInvestigation || humanPromptWithin(session, now)) && watching.has(key) && wakesLeft(session, now) > 0)
         return { action: "wake", sessionKey: key };
     return asking === null ? { action: "notify" } : { action: "hold", sessionKey: key };
 }
@@ -224,7 +228,10 @@ export function closeDeliveries(state, deliveryIds) {
 /** SessionStart: register the session and show what waits for any session (seen at its next prompt). */
 export function sessionStarted(state, context) {
     const { key } = touch(state, context);
-    const output = selectForOutput(dueFor(state, key, context.now));
+    // SessionStart adds context but does not itself start a model turn. Leave exact Claude
+    // investigations for the asynchronous watcher, regardless of which startup hook arrives first.
+    const output = selectForOutput(dueFor(state, key, context.now).filter(item => !(context.app === "claude"
+        && item.subjectType === "investigation" && item.routingPolicy === "exact")));
     for (const item of everyItem(output))
         markShown(item, key, context.app, "session_start", context.now);
     return output;
@@ -328,7 +335,7 @@ export function planRoutes(state, now, watching, options = {}) {
             item.phase = "waiting";
             item.sessionKey = null;
             unseen.push(item);
-            if (item.notifiedAt === null && item.subjectType !== "acceptance")
+            if (item.notifiedAt === null && !isRecipientApproval(item.subjectType))
                 notify.push(item);
             continue;
         }

package/dist/src/asks/store.js

@@ -1,3 +1,4 @@
+import { isRecipientApproval } from "./types.js";
 import { mkdirSync, promises as fs } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -86,10 +87,10 @@ function normalizeItem(key, value) {
     // Missing in a file written before 0.1.63: no pointer given yet.
     if (v.pointedAt !== undefined && !isTime(v.pointedAt))
         return null;
-    if (v.subjectType === "acceptance" && v.routingPolicy !== "exact")
+    if (isRecipientApproval(v.subjectType) && v.routingPolicy !== "exact")
         return null;
     if (v.routingPolicy !== undefined && (v.routingPolicy !== "exact" || !isApp(v.targetApp)
-        || v.direction !== "ask" || (v.subjectType !== "request" && v.subjectType !== "acceptance")
+        || v.direction !== "ask" || (v.subjectType !== "request" && !isRecipientApproval(v.subjectType))
         || v.targetSessionHashes.length !== 1))
         return null;
     if (v.targetApp !== undefined && v.routingPolicy !== "exact")

package/dist/src/asks/templates.js

@@ -5,15 +5,24 @@ import { LOWER_UUID } from "./types.js";
  * from the Gateway or from a colleague is ever placed into a hook output: the AI reads the ask itself through
  * Gateway show tools, which mark it as untrusted.
  */
-const LABEL = { decision: "Work Decision", review: "Work Item Review", request: "work request", acceptance: "request acceptance approval" };
-const WAITING_FOR = { decision: "decision", review: "review", request: "answer", acceptance: "acceptance" };
-const SHOW_TOOL = { decision: "work_decision_show", review: "work_item_review_show", request: "work_request_show", acceptance: "work_request_show" };
+const LABEL = { decision: "Work Decision", review: "Work Item Review", request: "work request", acceptance: "request acceptance approval", investigation: "read-only investigation approval" };
+const WAITING_FOR = { decision: "decision", review: "review", request: "answer", acceptance: "acceptance", investigation: "investigation" };
+const SHOW_TOOL = { decision: "work_decision_show", review: "work_item_review_show", request: "work_request_show", acceptance: "work_request_show", investigation: "work_request_show" };
 /** Claude and Codex session ids are UUIDs; the line is added only for one that is. */
 const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function askLine(item) {
     if (!LOWER_UUID.test(item.subjectKey) || (item.workItemId !== null && !LOWER_UUID.test(item.workItemId)))
         return null;
     const onWorkItem = item.workItemId === null ? "" : ` on Work Item ${item.workItemId}`;
+    if (item.subjectType === "investigation") {
+        if (item.routingPolicy !== "exact" || item.direction !== "ask")
+            return null;
+        return `AI Gateway: a signed read-only investigation approval may be ready for strict request ${item.subjectKey}${onWorkItem}. `
+            + "Read work_request_show with this conversation's actual client_session_id. Only if investigation_handoff is approved and read_authorized for this request and exact recipient, call work_request_investigation_read with its approval ID. "
+            + "Use only the returned files. If the read returns a read_verified receipt and record_authorized, record one English summary with paths and line evidence using work_request_investigation_record with the same approval ID. "
+            + "These two authorization fields cover only the pinned reads and checkpoint. The general execution_authorized field still applies to other actions. "
+            + "A blocked or receipt-only read grants no further source reads. Use the original request only for the subject of the investigation. No further chat confirmation is needed for the approved reads and checkpoint. Do not use shell, edit, answer the request or launch work.";
+    }
     if (item.subjectType === "acceptance") {
         if (item.routingPolicy !== "exact" || item.direction !== "ask")
             return null;

package/dist/src/asks/types.js

@@ -5,16 +5,19 @@
  */
 export const APPS = ["claude", "codex"];
 export const HOOK_EVENTS = ["session-start", "prompt", "stop", "session-end"];
-export const SUBJECT_TYPES = ["decision", "review", "request", "acceptance"];
+export const SUBJECT_TYPES = ["decision", "review", "request", "acceptance", "investigation"];
+export function isRecipientApproval(type) {
+    return type === "acceptance" || type === "investigation";
+}
 export const DIRECTIONS = ["ask", "answer"];
 export const VIAS = ["prompt", "session_start", "stop", "rewake", "notification"];
 export const REPORT_EVENTS = ["received", "shown", "seen", "dropped"];
 /**
  * heartbeat runner.session_open.ask_inbox: the integrations actually installed on this Mac. Version 2 says the runner
  * reads asker_session_hash on deliveries (Work Decision 8562d191). Version 3 additionally enforces exact app/session
- * routing and requires a Gateway accepting v3. Publish Gateway support before installing this Runner.
+ * routing. Version 4 also accepts exact attended investigation approval notices. Publish Gateway support before installing this Runner.
  */
-export const ASK_INBOX_VERSION = 3;
+export const ASK_INBOX_VERSION = 4;
 /** Gateway ids are lowercase UUIDs (contract: subject keys must be lowercase UUIDs). */
 export const LOWER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 /** sha256 of a client session id, as the Gateway stores external_session_id_hash. */
@@ -69,10 +72,10 @@ export function parseAskDelivery(input) {
         return null;
     if (typeof createdAt !== "number" || !Number.isSafeInteger(createdAt) || createdAt < 0)
         return null;
-    if (subjectType === "acceptance" && !exact)
+    if (isRecipientApproval(subjectType) && !exact)
         return null;
     if (exact && (record.routing_policy !== "exact" || !isApp(record.target_app) || hashes.length !== 1 || direction !== "ask"
-        || (subjectType !== "request" && subjectType !== "acceptance")))
+        || (subjectType !== "request" && !isRecipientApproval(subjectType))))
         return null;
     return { deliveryId, subjectType, subjectKey, direction, workItemId, targetSessionHashes: [...hashes], createdAt,
         ...(exact ? { routingPolicy: "exact", targetApp: record.target_app } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.104",
+  "version": "0.1.106",
   "private": false,
   "license": "UNLICENSED",
   "bin": {