@mnemom/mnemom 0.17.34 → 0.17.36

package/dist/commands/durable-questions.js

@@ -0,0 +1,161 @@
+/**
+ * The durable question verbs (S1 amendment 61, signed off by Wassim 2026-11-02; ROUTES.own_questions and
+ * ROUTES.own_answer):
+ *
+ *   mnemom agent sessions questions <name> [--all] [--json]
+ *   mnemom agent sessions answer <name> <qid|latest> [choice...] [--dismiss] [--json]
+ *
+ * A locked seat that calls AskUserQuestion records the question at the api (question.asked) instead
+ * of drawing a dialog nobody sees. `questions` lists them (the open ones by default), with the option
+ * the seat recommends marked; `answer` answers one (question.answered, via coding_agent) or dismisses
+ * it. Each choice is a 1-based option number (comma separated for a multi-select question), an
+ * option label, or free text; with several questions, one choice per question in order. The seat
+ * gets the answer either live (its hook is still waiting) or as its next inbox message.
+ *
+ * Every dependency is injected (`QuestionVerbDeps`), so each branch is unit-tested.
+ */
+import { answerFromChoice, QUESTION_ID_RE, questionAnswerResponseOk, questionListResponseOk, } from "../vendor/shared/durable-contract/question.js";
+import { DurableRefusal } from "../lib/durable/refusal.js";
+import { handleVerbError, refusalFromAnswer, resolveTarget, } from "./durable-verbs.js";
+const usage = (message) => new DurableRefusal({ code: "invalid_argument", message, fix: null, exit: 2 });
+async function listQuestions(deps, name) {
+    const row = await resolveTarget(deps.api, name);
+    const a = await deps.api.questions("own_questions", row.conversation_id, row.agent_id);
+    if (a.status !== 200 || !questionListResponseOk(a.body))
+        throw refusalFromAnswer(a, name, deps.launcherKey(), row);
+    return {
+        rows: a.body.questions,
+        cid: row.conversation_id,
+        agentId: row.agent_id,
+        raw: a.body,
+    };
+}
+/**
+ * Whether the owner can still answer `q`. The api reports a question the seat released as
+ * `handed_off` whether or not it was answered since (S1 question.ts: answered and handed_off can
+ * both hold), so a handed-off question is still waiting for the owner while it has no answered_at
+ * and has not expired. Its answer then reaches the seat as an inbox message (S1 §61 (c)/(e)).
+ */
+export function awaitingAnswer(q, now) {
+    if (q.state === "open")
+        return true;
+    return q.state === "handed_off" && q.answered_at === null && Date.parse(q.expires_at) > now;
+}
+/** The state the owner reads: a handed-off question still waiting for them says so. */
+function stateLabel(q, now) {
+    if (q.state !== "handed_off")
+        return q.state;
+    if (q.answered_at !== null)
+        return q.answers !== null ? "answered (handed off)" : "dismissed (handed off)";
+    return awaitingAnswer(q, now) ? "open (handed off: the answer goes to its inbox)" : "expired";
+}
+/**
+ * Text the seat's model wrote, made safe for the owner's terminal: every C0/C1 control character
+ * (ESC, CSI, OSC, BEL, CR, ...) and DEL is shown escaped (`\x1b`), so a question cannot move the
+ * cursor, rewrite or hide a line, or write the clipboard. S1 question.ts only refuses NUL.
+ */
+export function terminalSafe(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, (c) => {
+        const h = c.charCodeAt(0).toString(16).padStart(2, "0");
+        return `\\x${h}`;
+    });
+}
+/** The human lines for one question row. */
+export function renderQuestion(q, now = Date.now()) {
+    const t = terminalSafe;
+    const lines = [`question ${q.approval_id}  ${stateLabel(q, now)}  asked ${t(q.created_at)}`];
+    q.questions.forEach((item, i) => {
+        lines.push(`  ${item.header ? `[${t(item.header)}] ` : ""}${t(item.question)}${item.multiSelect ? "  (choose one or more)" : ""}`);
+        item.options.forEach((o, j) => {
+            const rec = q.recommended[i] === j ? "  <- recommended" : "";
+            lines.push(`    ${j + 1}. ${t(o.label)}${o.description ? ` - ${t(o.description)}` : ""}${rec}`);
+        });
+        const a = q.answers?.[item.question];
+        if (a !== undefined)
+            lines.push(`    answer: ${t(a)}`);
+    });
+    if (q.answered_via)
+        lines.push(`  answered via ${q.answered_via} at ${q.answered_at ?? "?"}`);
+    return lines;
+}
+export async function questionsCommand(name, opts, deps) {
+    const json = opts.json === true;
+    try {
+        const { rows, raw } = await listQuestions(deps, name);
+        const now = deps.now();
+        const shown = opts.all === true ? rows : rows.filter((r) => awaitingAnswer(r, now));
+        if (json) {
+            deps.out(JSON.stringify(opts.all === true ? raw : { questions: shown }));
+            return 0;
+        }
+        if (shown.length === 0) {
+            deps.out(`${name}: no ${opts.all === true ? "" : "open "}questions`);
+            return 0;
+        }
+        for (const q of shown)
+            for (const l of renderQuestion(q, now))
+                deps.out(l);
+        deps.out(`answer with: mnemom agent sessions answer ${name} <question id|latest> <choice>...`);
+        return 0;
+    }
+    catch (e) {
+        return handleVerbError(e, json, deps);
+    }
+}
+/** The answers map for one question row from the owner's choices (one per question, in order). */
+export function answersFromChoices(q, choices) {
+    if (choices.length !== q.questions.length)
+        throw usage(`question ${q.approval_id} has ${q.questions.length} question(s): give one choice for each, in order`);
+    const out = {};
+    q.questions.forEach((item, i) => {
+        const c = choices[i] ?? "";
+        if (c.trim() === "")
+            throw usage("an empty choice is not an answer");
+        out[item.question] = answerFromChoice(item, c);
+    });
+    return out;
+}
+export async function answerCommand(name, qid, choices, opts, deps) {
+    const json = opts.json === true;
+    const say = json ? deps.err : deps.out;
+    try {
+        const dismiss = opts.dismiss === true;
+        if (dismiss && choices.length > 0)
+            throw usage("--dismiss takes no choices");
+        if (!dismiss && choices.length === 0)
+            throw usage(`mnemom agent sessions answer ${name} <question id|latest> <choice>... (or --dismiss)`);
+        if (qid !== "latest" && !QUESTION_ID_RE.test(qid))
+            throw usage(`'${qid}' is not a question id (see mnemom agent sessions questions ${name})`);
+        const { rows, cid, agentId } = await listQuestions(deps, name);
+        const now = deps.now();
+        const open = rows.filter((r) => awaitingAnswer(r, now));
+        const q = qid === "latest" ? open[0] : rows.find((r) => r.approval_id === qid);
+        if (!q)
+            throw usage(qid === "latest" ? `${name} has no open question` : `${name} has no question ${qid}`);
+        if (!awaitingAnswer(q, now))
+            throw usage(`question ${q.approval_id} is already ${stateLabel(q, now)}`);
+        const body = dismiss
+            ? { approval_id: q.approval_id, via: "coding_agent", dismiss: true }
+            : {
+                approval_id: q.approval_id,
+                via: "coding_agent",
+                answers: answersFromChoices(q, choices),
+            };
+        const a = await deps.api.questions("own_answer", cid, agentId, body);
+        if (a.status !== 200 || !questionAnswerResponseOk(a.body))
+            throw refusalFromAnswer(a, name, deps.launcherKey());
+        const r = a.body;
+        say(r.outcome === "dismissed"
+            ? `${name}: question ${q.approval_id} dismissed`
+            : r.delivery === "live"
+                ? `${name}: answered; the waiting seat takes it now`
+                : `${name}: answered; it reaches the session as its next message (inbox ${r.inbox_id})`);
+        if (json)
+            deps.out(JSON.stringify(a.body));
+        return 0;
+    }
+    catch (e) {
+        return handleVerbError(e, json, deps);
+    }
+}

package/dist/commands/scan.d.ts

@@ -11,6 +11,7 @@ import { type AnthropicUsageDeps } from "../lib/scan/spend/anthropic-usage.js";
 import { type RecordDeps, type RecordOutcome } from "../lib/scan/record.js";
 import { type CostSpend } from "../lib/scan/cost-per-pr.js";
 import { type ReportEmailDeps } from "../lib/scan/report-email.js";
+import { type RepoListDeps } from "../lib/scan/repo-picker.js";
 import { type ReportRecipients } from "../lib/scan/share.js";
 export interface ScanCommandOptions {
     repos: string[];
@@ -42,12 +43,20 @@ export interface ScanCommandOptions {
     recordDeps?: RecordDeps;
     /** Test seam: the report-email POST. */
     emailDeps?: ReportEmailDeps;
+    /** Test seam: the org this login was authorized for (none of the stored tokens carry one today). */
+    authorizedOrg?: () => string | undefined;
+    /** Test seam: the `mnemom org use` default. */
+    activeOrg?: () => {
+        org_id: string;
+    } | undefined;
     /** Test seam: the signed-in user's orgs, used to infer --org when it is omitted. */
     listOrgs?: () => Promise<Array<{
         org_id: string;
         name?: string;
         is_personal?: boolean;
     }>>;
+    /** Test seam: the fetch behind the repo picker's list read. */
+    repoListDeps?: RepoListDeps;
     /** Test seams. */
     isTty?: boolean;
     env?: NodeJS.ProcessEnv;
@@ -93,9 +102,10 @@ export declare function resolveMeasuredUsage(o: ScanCommandOptions, period: {
 } | null>;
 /**
  * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
- * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
- * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
- * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ * needs an org. Order: --org; the org the login was authorized for; the `mnemom org use` default; the
+ * signed-in user's single non-personal membership (GET /v1/orgs); a terminal picker over several; else it
+ * stops loudly BEFORE any scan work, naming each org beside its id. It never guesses between orgs and
+ * never skips the email.
  */
 export declare function resolveScanOrg(o: ScanCommandOptions): Promise<string>;
 export declare const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";

package/dist/commands/scan.js

@@ -12,10 +12,12 @@ import { isSpendTiersEnabled, NOT_ENABLED_MSG, parseMonthlySpendUsd, selectSpend
 import { ADMIN_KEY_ENV, AnthropicUsageError, fetchMeasuredUsage, isAdminKeyShape, usageFailureText, } from "../lib/scan/spend/anthropic-usage.js";
 import { getAuthInfo } from "../lib/auth.js";
 import { listMyOrgs } from "../lib/api.js";
+import { getActiveOrg } from "../lib/cli-config.js";
 import { fetchRecordTotals, isOrgId, } from "../lib/scan/record.js";
 import { modelledSpend } from "../lib/scan/cost-per-pr.js";
 import { RECORD_NO_ORG_NOTE, renderRecordSection } from "../lib/scan/report.js";
 import { buildEmailBody, buildEmailReport, DRY_RUN_MSG, UNAVAILABLE_MSG, failureMessage, ReportEmailError, sendReportEmail, } from "../lib/scan/report-email.js";
+import { pickRepos, REPO_PICKER_NO_TERMINAL_HINT, } from "../lib/scan/repo-picker.js";
 import { buildSharePayload, parseShareLevel, promptShareLevel, } from "../lib/scan/share.js";
 /** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
 export function parseRepoFlags(raw) {
@@ -126,9 +128,10 @@ export async function resolveMeasuredUsage(o, period) {
 }
 /**
  * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
- * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
- * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
- * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ * needs an org. Order: --org; the org the login was authorized for; the `mnemom org use` default; the
+ * signed-in user's single non-personal membership (GET /v1/orgs); a terminal picker over several; else it
+ * stops loudly BEFORE any scan work, naming each org beside its id. It never guesses between orgs and
+ * never skips the email.
  */
 export async function resolveScanOrg(o) {
     if (o.org !== undefined) {
@@ -136,6 +139,18 @@ export async function resolveScanOrg(o) {
             throw new Error(INVALID_ORG_MSG);
         return o.org;
     }
+    // 2. The org this login was authorized for, when the token or session carries one.
+    const authorized = o.authorizedOrg?.();
+    if (authorized !== undefined) {
+        if (!isOrgId(authorized))
+            throw new Error(INVALID_ORG_MSG);
+        return authorized;
+    }
+    // 3. The default set with `mnemom org use <slug>` (a malformed stored id is ignored, not trusted).
+    const active = (o.activeOrg ?? getActiveOrg)()?.org_id;
+    if (active !== undefined && isOrgId(active))
+        return active;
+    // 4-6. Memberships: a single one, else a terminal picker, else fail closed.
     let orgs;
     try {
         orgs = (await (o.listOrgs ?? listMyOrgs)()).filter((x) => !x.is_personal);
@@ -147,8 +162,20 @@ export async function resolveScanOrg(o) {
         return orgs[0].org_id;
     if (orgs.length === 0)
         throw new Error("You belong to no organization, so the report has nowhere to be emailed from. Pass --org <org_id>.");
-    throw new Error(`You belong to ${orgs.length} organizations; pass --org <org_id> (${orgs.map((x) => x.org_id).join(", ")}).`);
+    // Several orgs: ids alone mean nothing, so show each name beside its id. A terminal picks one; anything
+    // else fails closed (never a guess) with the same labels in the message.
+    const labels = orgs.map(orgLabel);
+    if (o.isTty ?? process.stdin.isTTY) {
+        const chosen = await askSelect("Which organization should the report be emailed for?", labels);
+        const hit = orgs.find((x, i) => labels[i] === chosen);
+        if (hit && isOrgId(hit.org_id))
+            return hit.org_id;
+        throw new Error("No organization selected. Pass --org <org_id>.");
+    }
+    throw new Error(`You belong to ${orgs.length} organizations; pass --org <org_id> (${labels.join(", ")}).`);
 }
+/** "Name (org-id)", or just the id when the org has no usable name. */
+const orgLabel = (x) => typeof x.name === "string" && x.name.trim() !== "" ? `${x.name.trim()} (${x.org_id})` : x.org_id;
 export const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
 /**
  * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
@@ -168,23 +195,34 @@ export async function scanCommand(o) {
     if (o.share !== undefined && parseShareLevel(o.share) === null) {
         throw new Error("--share must be one of: summary, full, none");
     }
-    if (o.repos.length === 0)
-        throw new Error("--repo owner/name is required (repeatable)");
+    const noRepoFlag = o.repos.length === 0;
+    // No --repo: on a terminal pick from the repos this GitHub login can read; otherwise the error stays, with a hint.
+    if (noRepoFlag && !(o.isTty ?? process.stdin.isTTY))
+        throw new Error(`--repo owner/name is required (repeatable). ${REPO_PICKER_NO_TERMINAL_HINT}`);
     // The report is emailed on every scan, so resolve the org before any scan work; failure is loud.
     const emailOrg = await resolveScanOrg(o);
     if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
         throw new Error("--cto-email must be a valid email address");
+    const getCredential = async () => {
+        const c = o.credential ?? (await resolveCredential().catch(() => null));
+        if (!c)
+            throw new Error(failureText("credential"));
+        return c;
+    };
+    // Asked before the spend prompts so the repo comes first; the credential is reused for the scan.
+    const pickedCredential = noRepoFlag ? await getCredential() : null;
+    const repos = pickedCredential
+        ? await pickRepos(pickedCredential, { isTty: true, deps: o.repoListDeps })
+        : o.repos;
     const selfReported = await resolveSelfReportedSpend(o);
     const now = o.now ?? Date.now;
     const end = new Date(now()).toISOString().slice(0, 10);
     const period = o.period ?? { start: end, end };
     const measured = await resolveMeasuredUsage(o, period);
-    const credential = o.credential ?? (await resolveCredential().catch(() => null));
-    if (!credential)
-        throw new Error(failureText("credential"));
+    const credential = pickedCredential ?? (await getCredential());
     // Before the local scan: a refused credential fails closed without spending the GitHub reads.
     const record = await resolveRecordOutcome(o);
-    const outcome = await runLocalScan({ credential, now, ...o.deps }, { repos: o.repos, period });
+    const outcome = await runLocalScan({ credential, now, ...o.deps }, { repos, period });
     if (outcome.status === "withheld")
         throw new Error(`Scan withheld: ${failureText(outcome.reason)}`);
     const { result } = outcome;

package/dist/durable/seat-proxy.d.ts

@@ -51,7 +51,10 @@ export declare function armVerdict(pathname: string, rawHeaders: readonly string
     forward: false;
     reason: DropReason;
 };
-/** The dead-key signal in a door response (C13-R7), read from the JSON body's error.type. */
+/**
+ * The dead-key signal in a door response (C13-R7), read from the JSON body's error.code: the
+ * gateway's durable refusals are durableErrorBody, `{error:{code, message}}`, with no error.type.
+ */
 export declare function deadKeyReason(status: number, body: string): ExitReason | null;
 /** Whether a request path is origin-form and free of dot segments (raw or percent-encoded). */
 export declare function isCleanOriginForm(url: string): boolean;
@@ -71,6 +74,14 @@ export interface SeatProxyDeps {
 export interface SeatProxyState {
     dead: ExitReason | null;
 }
+/**
+ * The dead-candidate body as text, decoded by its content-encoding (gzip, deflate, br; identity or
+ * absent passes through; a comma list is undone last-applied first). The decoded size is capped too
+ * (zlib maxOutputLength), so a decompression bomb cannot blow up memory. Returns null when the body
+ * cannot be decoded: corrupt bytes, an unknown encoding, or over the cap once decoded. For the dead-key
+ * check only; the forwarded response keeps the original bytes.
+ */
+export declare function decodeDeadBody(buf: Buffer, contentEncoding: string | undefined, cap: number): string | null;
 /** The request handler of a seat proxy for `cfg` with lease key `key`. */
 export declare function createSeatProxyHandler(cfg: SeatProxyArgs, key: string, deps: SeatProxyDeps, state?: SeatProxyState): (req: http.IncomingMessage, res: http.ServerResponse) => void;
 export interface SeatProxyMainDeps {

package/dist/durable/seat-proxy.js

@@ -20,6 +20,7 @@ import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
 import os from "node:os";
+import zlib from "node:zlib";
 import { randomBytes } from "node:crypto";
 import { TurnOrigins, claudeConfigDir, TURN_HEADER } from "../turn-origin.mjs";
 import { httpDoorAllowed } from "./test-mode.mjs";
@@ -190,26 +191,29 @@ export function armVerdict(pathname, rawHeaders) {
         reason: a.hold !== "on" ? "unattended_hold_off" : "unattended_fence_off",
     };
 }
-/** The dead-key signal in a door response (C13-R7), read from the JSON body's error.type. */
+/**
+ * The dead-key signal in a door response (C13-R7), read from the JSON body's error.code: the
+ * gateway's durable refusals are durableErrorBody, `{error:{code, message}}`, with no error.type.
+ */
 export function deadKeyReason(status, body) {
     if (status !== 401 && status !== 409 && status !== 410)
         return null;
-    let type;
+    let code;
     try {
         const j = JSON.parse(body);
-        type =
+        code =
             j && typeof j === "object" && j.error && typeof j.error === "object"
-                ? j.error.type
+                ? j.error.code
                 : undefined;
     }
     catch {
         return null;
     }
-    if (status === 409 && type === "durable_lease_fenced")
+    if (status === 409 && code === "durable_lease_fenced")
         return "fenced_exit";
-    if (status === 401 && type === "durable_key_revoked")
+    if (status === 401 && code === "durable_key_revoked")
         return "revoked_exit";
-    if (status === 410 && (type === "durable_session_ended" || type === "durable_unlocked"))
+    if (status === 410 && (code === "durable_session_ended" || code === "durable_unlocked"))
         return "ended_exit";
     return null;
 }
@@ -252,6 +256,45 @@ function sendLocal(res, status, type, message) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify({ type: "error", error: { type, message } }));
 }
+/**
+ * The dead-candidate body as text, decoded by its content-encoding (gzip, deflate, br; identity or
+ * absent passes through; a comma list is undone last-applied first). The decoded size is capped too
+ * (zlib maxOutputLength), so a decompression bomb cannot blow up memory. Returns null when the body
+ * cannot be decoded: corrupt bytes, an unknown encoding, or over the cap once decoded. For the dead-key
+ * check only; the forwarded response keeps the original bytes.
+ */
+export function decodeDeadBody(buf, contentEncoding, cap) {
+    const encs = (contentEncoding ?? "")
+        .split(",")
+        .map((e) => e.trim().toLowerCase())
+        .filter((e) => e !== "" && e !== "identity");
+    const opts = { maxOutputLength: Math.max(cap, 1) };
+    try {
+        let out = buf;
+        for (const enc of encs.reverse()) {
+            if (enc === "gzip" || enc === "x-gzip")
+                out = zlib.gunzipSync(out, opts);
+            else if (enc === "br")
+                out = zlib.brotliDecompressSync(out, opts);
+            else if (enc === "deflate") {
+                try {
+                    out = zlib.inflateSync(out, opts);
+                }
+                catch (e) {
+                    if (e instanceof RangeError)
+                        throw e;
+                    out = zlib.inflateRawSync(out, opts); // some servers send raw deflate
+                }
+            }
+            else
+                return null;
+        }
+        return out.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
 /** Thrown by readAll when a body passes its cap. */
 class OverCap extends Error {
 }
@@ -393,15 +436,18 @@ export function createSeatProxyHandler(cfg, key, deps, state = { dead: null }) {
             const deadCandidate = status === 401 || status === 409 || status === 410;
             if (deadCandidate) {
                 void readAll(ur, deadBodyCap).then((buf) => {
-                    const dead = deadKeyReason(status, buf.toString("utf8"));
+                    const text = decodeDeadBody(buf, ur.headers["content-encoding"], deadBodyCap);
+                    const dead = text === null ? null : deadKeyReason(status, text);
                     if (dead)
                         state.dead = dead;
                     if (verdict.forward) {
+                        if (text === null)
+                            deps.log(`${pathname} ${status} undecodable_body`);
                         res.writeHead(status, responseHeaders(ur.rawHeaders));
                         res.end(buf);
                     }
                     else {
-                        deps.log(`${pathname} ${status} drop ${verdict.reason}`);
+                        deps.log(`${pathname} ${status} drop ${text === null ? "undecodable_body" : verdict.reason}`);
                         sendDrop(res, reqId());
                     }
                     if (dead) {

package/dist/durable/seat-socket.d.ts

@@ -3,6 +3,8 @@ import net from "node:net";
 export declare const SEAT_SOCKET_REFUSAL = "{\"ok\":false,\"error\":\"seat_op_refused\"}";
 /** Our own hello cannot reach the daemon (no relay configured, or the relay failed). */
 export declare const SEAT_SOCKET_UNAVAILABLE = "{\"ok\":false,\"error\":\"seat_hello_unavailable\"}";
+/** A question op that cannot reach the daemon (no relay configured, or the relay failed). */
+export declare const SEAT_SOCKET_QUESTION_UNAVAILABLE = "{\"ok\":false,\"error\":\"seat_question_unavailable\"}";
 /** A frame (the bytes before the newline) longer than this many bytes is refused without parsing. */
 export declare const SEAT_SOCKET_MAX_FRAME: number;
 /** macOS sun_path is 104 bytes including the NUL. */
@@ -13,12 +15,28 @@ export interface SeatIdentity {
     epoch: number;
     spawnId: string;
 }
-export type HelloRelay = (frame: {
+/** S1 amendment 61: the seat's question ops (seat-ask.mjs). */
+export declare const SEAT_QUESTION_OPS: readonly ["question_ask", "question_poll", "question_release"];
+export type SeatQuestionOp = (typeof SEAT_QUESTION_OPS)[number];
+export type SeatRelayFrame = {
     op: "hello";
     session_id: string;
     epoch: number;
     spawn_id: string;
-}) => Promise<string>;
+} | {
+    op: SeatQuestionOp;
+    session_id: string;
+    epoch: number;
+    spawn_id: string;
+    [k: string]: unknown;
+};
+/** One frame to the daemon's control socket, its one-line answer back. */
+export type HelloRelay = (frame: SeatRelayFrame) => Promise<string>;
+/**
+ * The relay frame for the seat's own question op, or null (refused). Session, spawn id and epoch
+ * must all be the seat's own (epoch required); the payload must be the op's exact shape.
+ */
+export declare function ownQuestionFrame(frame: unknown, seat: SeatIdentity | null): SeatRelayFrame | null;
 /** Whether a parsed frame is the seat's own hello. Everything else is refused. */
 export declare function isOwnHello(frame: unknown, seat: SeatIdentity | null): boolean;
 /** The reply line (without newline) for one request line. Never throws. */

package/dist/durable/seat-socket.js

@@ -10,19 +10,63 @@
 // the hook unchanged; a repeat hello is relayed like the first. Every other op, and any op naming
 // another session id or spawn id, gets the one fixed refusal line below, with no relay and no API
 // call. The refusal echoes nothing from the request.
+//
+// S1 amendment 61 (signed off by Wassim 2026-11-02) adds three question ops, relayed the same way and
+// only for the seat's own session, spawn id AND epoch (required here, not optional as for hello):
+//   {op:"question_ask", tool_use_id, questions}   the plugin's AskUserQuestion PreToolUse hook
+//   {op:"question_poll", approval_id}             while that hook waits for the owner
+//   {op:"question_release", approval_id}          the hook stopped waiting; the answer goes to the inbox
+// The payload is checked against S1 question.ts's shapes before any relay; the daemon adds the
+// epoch and nonce of the live lease and calls the executor question routes.
 import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { createHash } from "node:crypto";
+import { normalizeQuestions, QUESTION_TOOL_USE_ID_RE } from "../vendor/durable-contract/index.js";
 /** The one fixed refusal line (bytes before the newline). A local literal: S1 freezes no seat-socket refusal line yet (gap c3-seat-proxy-enums-not-in-s1). */
 export const SEAT_SOCKET_REFUSAL = '{"ok":false,"error":"seat_op_refused"}';
 /** Our own hello cannot reach the daemon (no relay configured, or the relay failed). */
 export const SEAT_SOCKET_UNAVAILABLE = '{"ok":false,"error":"seat_hello_unavailable"}';
+/** A question op that cannot reach the daemon (no relay configured, or the relay failed). */
+export const SEAT_SOCKET_QUESTION_UNAVAILABLE = '{"ok":false,"error":"seat_question_unavailable"}';
 /** A frame (the bytes before the newline) longer than this many bytes is refused without parsing. */
 export const SEAT_SOCKET_MAX_FRAME = 64 * 1024;
 /** macOS sun_path is 104 bytes including the NUL. */
 export const SOCKET_PATH_MAX = 103;
+/** S1 amendment 61: the seat's question ops (seat-ask.mjs). */
+export const SEAT_QUESTION_OPS = ["question_ask", "question_poll", "question_release"];
+const UUID_LC = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * The relay frame for the seat's own question op, or null (refused). Session, spawn id and epoch
+ * must all be the seat's own (epoch required); the payload must be the op's exact shape.
+ */
+export function ownQuestionFrame(frame, seat) {
+    if (!seat || !frame || typeof frame !== "object" || Array.isArray(frame))
+        return null;
+    const f = frame;
+    if (!SEAT_QUESTION_OPS.includes(f.op))
+        return null;
+    if (f.session_id !== seat.sessionId || f.spawn_id !== seat.spawnId || f.epoch !== seat.epoch)
+        return null;
+    const base = { session_id: seat.sessionId, epoch: seat.epoch, spawn_id: seat.spawnId };
+    const keys = Object.keys(f).sort().join(",");
+    if (f.op === "question_ask") {
+        if (keys !== "epoch,op,questions,session_id,spawn_id,tool_use_id")
+            return null;
+        if (typeof f.tool_use_id !== "string" || !QUESTION_TOOL_USE_ID_RE.test(f.tool_use_id))
+            return null;
+        const questions = normalizeQuestions(f.questions);
+        if (!questions)
+            return null;
+        return { op: "question_ask", ...base, tool_use_id: f.tool_use_id, questions };
+    }
+    if (keys !== "approval_id,epoch,op,session_id,spawn_id")
+        return null;
+    if (typeof f.approval_id !== "string" || !UUID_LC.test(f.approval_id))
+        return null;
+    return { op: f.op, ...base, approval_id: f.approval_id };
+}
 /** Whether a parsed frame is the seat's own hello. Everything else is refused. */
 export function isOwnHello(frame, seat) {
     if (!seat || !frame || typeof frame !== "object" || Array.isArray(frame))
@@ -48,6 +92,20 @@ export async function answerFrame(line, seat, relay) {
     catch {
         return { reply: SEAT_SOCKET_REFUSAL, outcome: "refused" };
     }
+    const question = ownQuestionFrame(frame, seat);
+    if (question) {
+        if (!relay)
+            return { reply: SEAT_SOCKET_QUESTION_UNAVAILABLE, outcome: "unavailable" };
+        try {
+            const first = String(await relay(question)).split("\n")[0];
+            return first
+                ? { reply: first, outcome: "relayed" }
+                : { reply: SEAT_SOCKET_QUESTION_UNAVAILABLE, outcome: "unavailable" };
+        }
+        catch {
+            return { reply: SEAT_SOCKET_QUESTION_UNAVAILABLE, outcome: "unavailable" };
+        }
+    }
     if (!isOwnHello(frame, seat) || !seat)
         return { reply: SEAT_SOCKET_REFUSAL, outcome: "refused" };
     if (!relay)

package/dist/durable/turn-chain.d.ts

@@ -36,6 +36,14 @@ export declare function statedEntry(e: TranscriptEntry): TranscriptEntry;
  * origin=task entries only (S1 amendment 56); undefined otherwise or when not a TURN_PRODUCER_RE token.
  */
 export declare function entryProducer(e: TranscriptEntry): string | undefined;
+/**
+ * The inbox sha an entry answers (S1 amendment 60): the `[mnemom inbox <sha>]` marker on the first
+ * line of the entry's first text (after Claude Code's paste open tag, as the host daemon delivers by
+ * bracketed paste), else undefined. Only a prompt entry stated as human can carry one: a task or
+ * system entry that quotes a marker never does. Restrict-only: the stamp only makes a turn
+ * unattended, and the gateway admits it only while the sha is open (delivered, not acked).
+ */
+export declare function entryInboxSha(e: TranscriptEntry): string | undefined;
 /** The header value: the leading chain element, then the stated entries up to and including the root. */
 export declare function durableHeaderValue(entries: readonly TranscriptEntry[], chain: string): string;
 /** Entries up to and including the last one whose promptId is `promptId`; none when it is absent. */

package/dist/durable/turn-chain.js

@@ -24,9 +24,10 @@
 // origin.producer, e.g. session-task), here only. turn-origin.mjs is main's, so the plain proxies'
 // header bytes never carry it.
 import { createHash } from "node:crypto";
-import { buildTurnHeader, entryOrigin, entrySource, TURN_PARTS_MAX, } from "../turn-origin.mjs";
+import { buildTurnHeader, entryOrigin, entrySource, entryTexts, TURN_PARTS_MAX, } from "../turn-origin.mjs";
 import { TURN_WAIT_MS, isCountTokensPath, } from "../vendor/durable-contract/index.js";
 import { TURN_PRODUCER_RE } from "../vendor/shared/durable-contract/turn.js";
+import { inboxMarkerOf } from "../vendor/shared/durable-contract/inbox.js";
 const ID_RE = /^[A-Za-z0-9-]{8,64}$/;
 const POLL_MS = 20;
 const one = (v) => String((Array.isArray(v) ? v[0] : v) ?? "").trim();
@@ -84,9 +85,26 @@ export function entryProducer(e) {
     const p = e.origin?.producer;
     return typeof p === "string" && TURN_PRODUCER_RE.test(p) ? p : undefined;
 }
+/** Claude Code's open tag for a bracketed paste, which may lead a pasted prompt's text. */
+const PASTE_OPEN_RE = /^<pasted_content id="[^"\n]{0,128}">\n?/;
+/**
+ * The inbox sha an entry answers (S1 amendment 60): the `[mnemom inbox <sha>]` marker on the first
+ * line of the entry's first text (after Claude Code's paste open tag, as the host daemon delivers by
+ * bracketed paste), else undefined. Only a prompt entry stated as human can carry one: a task or
+ * system entry that quotes a marker never does. Restrict-only: the stamp only makes a turn
+ * unattended, and the gateway admits it only while the sha is open (delivered, not acked).
+ */
+export function entryInboxSha(e) {
+    if (entryOrigin(e) !== "human" || entrySource(e) === "system")
+        return undefined;
+    const first = entryTexts(e)[0];
+    if (typeof first !== "string")
+        return undefined;
+    return inboxMarkerOf(first.replace(PASTE_OPEN_RE, "")) ?? undefined;
+}
 /**
  * main's buildTurnHeader, entry by entry, with `producer=<p>; ` before `pastes=` on an entry that
- * states one; the same newest TURN_PARTS_MAX parts.
+ * states one and `; inbox=<sha>` after `h=` on an inbox delivery; the same newest TURN_PARTS_MAX parts.
  */
 function statedParts(stated) {
     const parts = [];
@@ -95,8 +113,11 @@ function statedParts(stated) {
         if (!own)
             continue;
         const producer = entryProducer(e);
-        for (const part of own.split(", "))
-            parts.push(producer ? part.replace("; pastes=", `; producer=${producer}; pastes=`) : part);
+        const inbox = entryInboxSha(e);
+        for (const part of own.split(", ")) {
+            const p = producer ? part.replace("; pastes=", `; producer=${producer}; pastes=`) : part;
+            parts.push(inbox ? `${p}; inbox=${inbox}` : p);
+        }
     }
     return parts.slice(-TURN_PARTS_MAX).join(", ");
 }