@mattstack/rt-client 0.20.0 → 0.23.0

package/dist/client.d.ts

@@ -187,6 +187,7 @@ export declare function paneFocus(a: Commands["pane:focus"]["payload"], o?: RtCl
 export declare function reconcilerStatus(o?: RtClientOptions): Promise<RtResponse<Commands["reconciler:status"]["data"]>>;
 export declare function reconcilerClear(a: Commands["reconciler:clear"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["reconciler:clear"]["data"]>>;
 export declare function gateOpen(a: Commands["gate:open"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:open"]["data"]>>;
+export declare function gateAsk(a: Commands["gate:ask"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:ask"]["data"]>>;
 export declare function gateAnswer(a: Commands["gate:answer"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:answer"]["data"]>>;
 /** Daemon clamps its own wait to 240s (gates-store.ts); the client abort
     must outlive that cap, same +10s buffer as commands/events.ts's

package/dist/commands.d.ts

@@ -107,12 +107,14 @@ export type ExecutorState = "live" | "blocked" | "hidden" | "gone" | "cleared" |
 export type GateOption = string | {
     value: string;
     label: string;
+    recommended?: boolean;
 };
 export interface GateOrigin {
     paneId?: string;
     tabId?: string;
     runId?: string;
     worktree?: string;
+    surface?: string;
     presentation?: "form" | "wait";
 }
 export interface GateQuestion {
@@ -123,6 +125,11 @@ export interface GateQuestion {
 }
 export declare function gateOptionValue(o: GateOption): string;
 export declare function gateOptionLabel(o: GateOption): string;
+/** `session` is the answering surface's own session id, recorded so the
+    push facility can tell a self-answer from a remote one and skip the
+    doorbell it would otherwise send back to the writer. Optional: a caller
+    that supplies none (the board status-bin answers `by: "pane"` with no
+    session) still matches self by `by === GATE_BY_PANE`. */
 export interface GateAnswer {
     answers: Record<string, string | string[] | {
         value: string | string[];
@@ -131,6 +138,7 @@ export interface GateAnswer {
     by: string;
     answeredAt: number;
     overridden?: boolean;
+    session?: string;
 }
 export interface GateRow {
     id: string;
@@ -161,6 +169,15 @@ export interface GateRow {
         at: number;
     } | null;
     released: boolean;
+    /** Set once the nudged pane has provably read the answer: either it
+        self-answered (stamped in the same transaction as the answer) or a
+        later `markConsumed` call recorded that it acted on a push. `null`
+        until then, so a sweep can tell an answered-but-unread row from a
+        settled one. Currently only stamped for herd-subject gates (the
+        self-answer path and `rt herd answer`'s nudged-session read); a
+        non-herd gate with a nudge stays `null` even after its pane
+        reconciles. */
+    consumedAt: number | null;
     owner: string | null;
     escalatedAt: number | null;
     /** Set by answer-time execution handling: an answered gate whose executor
@@ -216,7 +233,7 @@ export interface HerdJobInfo {
     createdAt: number;
     updatedAt: number;
 }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. */
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
     herd: HerdInfo;
     jobs: Array<HerdJobInfo & {
@@ -224,6 +241,7 @@ export interface HerdStatusData {
         paneStatus: string | null;
         lastGateStatus: GateStatus | null;
         lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null;
+        lastGateConsumed: boolean | null;
     }>;
     unread: number;
     lifecycleConnected: boolean;
@@ -1329,6 +1347,29 @@ export interface Commands {
         };
         data: DiscussionsDiffsData;
     };
+    /** Positioned inline MR comment with server-side DiffNote verification:
+        posts, re-checks the created note's type from the creation response,
+        and on the silent general-note degrade deletes the stray note and
+        retries ONCE with freshly fetched diff_refs. The retry repairs only
+        the stale-diff-refs degrade; a caller-supplied position GitLab
+        rejects stays rejected, and after a second degrade both stray notes
+        are deleted and the call fails. `verified: true` means the check ran. */
+    "mr:comment-inline": {
+        payload: {
+            repoName: string;
+            iid: number;
+            body: string;
+            path: string;
+            line: number;
+            oldPath?: string;
+            oldLine?: number;
+        };
+        data: {
+            discussionId: string;
+            noteId: number;
+            verified: true;
+        };
+    };
     /** Wire reply is `{ok:true}` on success (no `data`); a failure is `{ok:false,error}`. */
     "mr:action": {
         payload: {
@@ -1432,6 +1473,41 @@ export interface Commands {
             supersededId: string | null;
         };
     };
+    /** Ceremony layer over gate:open: resolves subject from the caller's
+        session (an explicit subject always wins as the subject, but still
+        picks up run linkage from the session's own running run; else its
+        single running run as `run:<id>`; else its agent record's recorded
+        subject, or `agent:<id>` when it has none), computes
+        presentation via gatePresentation, supplies nudge/origin, and omits an
+        oversized context instead of rejecting it. `meta` and `agent` forward
+        to gate:open verbatim; `origin` passthrough fields fill gaps in the
+        ceremony's own origin (presentation, paneId, runId, run-derived
+        worktree always win over a caller-supplied value for the same key).
+        Delegates to gate:open for everything else (validation, supersede,
+        events, push). */
+    "gate:ask": {
+        payload: {
+            questions: GateQuestion[];
+            context?: string;
+            kind?: string;
+            subject?: string;
+            sessionId?: string;
+            paneId?: string;
+            meta?: Record<string, unknown>;
+            agent?: string;
+            origin?: {
+                surface?: string;
+                tabId?: string;
+                worktree?: string;
+            };
+        };
+        data: {
+            id: string;
+            presentation: "form" | "wait";
+            subject: string;
+            supersededId: string | null;
+        };
+    };
     /**
      * A CAS loss is a DEFINED OUTCOME, not an error: `ok:true` with
      * `conflict:true` and the WINNING row, so every consumer gets the winner
@@ -1652,6 +1728,7 @@ export interface Commands {
     "herd:answer": {
         payload: {
             gate: string;
+            sessionId?: string;
         };
         data: {
             gate: string;

package/dist/gate-answers.d.ts

@@ -0,0 +1,10 @@
+import type { GateQuestion, GateAnswer } from "./commands.ts";
+export type GateAnswerWire = GateAnswer["answers"][string];
+/** Both wire shapes carry the same value underneath: bare, or {value, note?}
+    when a panel attaches free text. Validation reads only the value. */
+export declare function unwrapGateAnswerValue(raw: unknown): unknown;
+/** Option membership is required whenever a question declares options,
+    checked against the unwrapped value (every element, for multi); an
+    empty options array stays free-form. Every question id must appear as
+    an answers key. Error strings are a wire contract; packages/rt-client/test/gate-answers.test.ts pins them verbatim. */
+export declare function validateGateAnswers(questions: GateQuestion[], answers: Record<string, unknown>): string | null;

package/dist/gate-options.d.ts

@@ -0,0 +1,22 @@
+import type { GateOption, GateQuestion } from "./commands.ts";
+/** The canonical stored/emitted option shape (contract C11). GateOption
+    (the input union) is unchanged; rows normalized by the daemon always
+    satisfy this. */
+export interface GateOptionObject {
+    value: string;
+    label: string;
+}
+/** Bare string s becomes {value: s, label: s}; a well-formed {value,label}
+    object passes through untouched. Total over whatever actually arrives
+    on the wire, not just the declared GateOption union: a partial object
+    fills the missing field from the one present, and anything else
+    (null, a number, an object with neither field) is coerced via String()
+    into both fields. The resulting label is then capitalized when
+    word-like (see isWordLikeLabel), and an object form's `recommended:
+    true` lifts into a " (Recommended)" label suffix -- guarded against
+    double-appending -- since `recommended` itself does not survive into
+    the returned object; the suffix IS its wire representation. Every
+    returned entry is a full {value,label} pair -- callers may trust the
+    return type without re-checking it. Pure and order-preserving. */
+export declare function normalizeGateOptions(options: GateOption[]): GateOptionObject[];
+export declare function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[];

package/dist/gate-presentation.d.ts

@@ -0,0 +1,10 @@
+import type { GateQuestion } from "./commands.ts";
+export declare const GATE_FORM_OPTION_CAP = 4;
+/** The ONE presentation rule (spec Phase 1): form iff an injectable pane
+    exists, a nudge target exists, and every question fits the native form's
+    per-question option cap. */
+export declare function gatePresentation(args: {
+    paneId?: string | undefined;
+    sessionId?: string | undefined;
+    questions: GateQuestion[];
+}): "form" | "wait";

package/dist/index.d.ts

@@ -1,7 +1,12 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
-export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, reconcilerStatus, reconcilerClear, gateOpen, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, reconcilerStatus, reconcilerClear, gateOpen, gateAsk, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
+export { GATE_FORM_OPTION_CAP, gatePresentation } from "./gate-presentation.ts";
+export { normalizeGateOptions, normalizeGateQuestions } from "./gate-options.ts";
+export type { GateOptionObject } from "./gate-options.ts";
+export { unwrapGateAnswerValue, validateGateAnswers } from "./gate-answers.ts";
+export type { GateAnswerWire } from "./gate-answers.ts";
 export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, ChatClaimOutcome, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ExecutorState, ExecutorView, ReconcilerStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, PaneDelivery, PaneSendResult, PaneFocusResult, GateStatus, GateOption, GateOrigin, GateQuestion, GateAnswer, GateRow, GateSubscription, HerdInfo, HerdListRow, HerdJobInfo, HerdStatusData, } from "./commands.ts";
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";

package/dist/index.js

@@ -288,6 +288,13 @@ function gateOpen(a, o = {}) {
       payload[k] = a[k];
   return rtCommand("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
+function gateAsk(a, o = {}) {
+  const payload = { questions: a.questions };
+  for (const k of ["context", "kind", "subject", "sessionId", "paneId", "meta", "agent", "origin"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("gate:ask", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
 function gateAnswer(a, o = {}) {
   const payload = { id: a.id, answers: a.answers, by: a.by };
   for (const k of ["session", "override"])
@@ -359,7 +366,8 @@ function herdMilestone(a, o = {}) {
   return rtCommand("herd:milestone", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function herdAnswer(a, o = {}) {
-  return rtCommand("herd:answer", { gate: a.gate }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+  const payload = { gate: a.gate, ...a.sessionId !== undefined ? { sessionId: a.sessionId } : {} };
+  return rtCommand("herd:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function herdReport(a, o = {}) {
   return rtCommand("herd:report", { herd: a.herd, job: a.job, body: a.body }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
@@ -477,6 +485,7 @@ var COMMAND_NAMES = [
   "discussions:resolve",
   "discussions:reply",
   "discussions:diffs",
+  "mr:comment-inline",
   "mr:action",
   "mr:fetch-job-detail",
   "mr:fetch-job-trace",
@@ -489,6 +498,7 @@ var COMMAND_NAMES = [
   "reconciler:status",
   "reconciler:clear",
   "gate:open",
+  "gate:ask",
   "gate:answer",
   "gate:wait",
   "gate:list",
@@ -530,6 +540,92 @@ var COMMAND_NAMES = [
   "bg:stop",
   "bg:release"
 ];
+// src/gate-presentation.ts
+var GATE_FORM_OPTION_CAP = 4;
+function gatePresentation(args) {
+  if (!args.paneId || !args.sessionId)
+    return "wait";
+  return args.questions.every((q) => q.options.length <= GATE_FORM_OPTION_CAP) ? "form" : "wait";
+}
+// src/gate-options.ts
+var RECOMMENDED_SUFFIX = " (Recommended)";
+var HAS_RECOMMENDED_SUFFIX = /\(\s*recommended\s*\)\s*$/i;
+function isWordLikeLabel(label) {
+  return /^[a-z][^A-Z0-9/:\\@]*$/.test(label);
+}
+function capitalize(label) {
+  return isWordLikeLabel(label) ? label[0].toUpperCase() + label.slice(1) : label;
+}
+function normalizeGateOptions(options) {
+  return options.map((o) => {
+    const recommended = o !== null && typeof o === "object" && o.recommended === true;
+    let value;
+    let label;
+    if (typeof o === "string") {
+      value = o;
+      label = o;
+    } else if (o !== null && typeof o === "object") {
+      const v = typeof o.value === "string" ? o.value : undefined;
+      const l = typeof o.label === "string" ? o.label : undefined;
+      value = v ?? l ?? String(o);
+      label = l ?? v ?? String(o);
+    } else {
+      value = String(o);
+      label = String(o);
+    }
+    label = capitalize(label);
+    if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
+      label += RECOMMENDED_SUFFIX;
+    return { value, label };
+  });
+}
+function normalizeGateQuestions(questions) {
+  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+}
+// src/gate-answers.ts
+function unwrapGateAnswerValue(raw) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && "value" in raw) {
+    return raw.value;
+  }
+  return raw;
+}
+function wrapperNoteIsValid(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !("value" in raw)) {
+    return true;
+  }
+  const note = raw.note;
+  return note === undefined || typeof note === "string";
+}
+function validateGateAnswers(questions, answers) {
+  const byId = new Map(questions.map((q) => [q.id, q]));
+  for (const [qid, raw] of Object.entries(answers)) {
+    const question = byId.get(qid);
+    if (!question)
+      return `unknown question id: ${qid}`;
+    if (!wrapperNoteIsValid(raw))
+      return `question ${qid} note must be a string`;
+    const value = unwrapGateAnswerValue(raw);
+    const isArray = Array.isArray(value);
+    if (question.multi && !isArray)
+      return `question ${qid} expects an array (multi)`;
+    if (!question.multi && isArray)
+      return `question ${qid} expects a single value`;
+    const values = isArray ? value : [value];
+    if (!values.every((v) => typeof v === "string"))
+      return `question ${qid} value must be a string`;
+    if (question.options.length > 0) {
+      const members = question.options.map(gateOptionValue);
+      for (const v of values) {
+        if (!members.includes(v))
+          return `answer for "${qid}" is not one of its options: "${v}"`;
+      }
+    }
+  }
+  const missing = questions.map((q) => q.id).filter((id) => !Object.prototype.hasOwnProperty.call(answers, id));
+  if (missing.length > 0)
+    return `missing answer(s) for: ${missing.join(", ")}`;
+  return null;
+}
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
 function subscribe(onEvent, opts = {}) {
@@ -840,7 +936,7 @@ var REGISTRY = [
     scopes: ["user"],
     default: [],
     merge: "replace",
-    description: 'Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message, subjectPrefix?, url?, owner?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload\'s first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload\'s subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification\'s Open target; a gate rule should set it. The optional owner field (only literal "human" is valid) suppresses events whose payload.owner starts with "herd:", allowing gate rules to skip herd-owned events. A typical setup pairs a gate/opened rule with owner: "human" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A fresh key, not an ownership-latch port, so a default is fine here.'
+    description: 'Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message, subjectPrefix?, url?, owner?, surface?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload\'s first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload\'s subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification\'s Open target; a gate rule should set it. The optional owner field (only literal "human" is valid) suppresses events whose payload.owner starts with "herd:", allowing gate rules to skip herd-owned events. The optional surface field (a string) matches only events whose payload.origin.surface equals the given value, allowing a rule to fire only for gates opened by a specific surface (e.g. surface: "board" matches only board-originated gates). A typical setup pairs a gate/opened rule with owner: "human" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A board-specific rule can combine surface: "board" with a board URL to open the decision queue directly. A fresh key, not an ownership-latch port, so a default is fine here.'
   },
   {
     key: "rt.cron",
@@ -2262,6 +2358,8 @@ async function resolveNameToIdentity(name, reposJsonPath) {
 }
 export {
   validateValue,
+  validateGateAnswers,
+  unwrapGateAnswerValue,
   unsetSetting,
   subscribe,
   setSettingsWarnSink,
@@ -2289,6 +2387,8 @@ export {
   paneAccounts,
   openSmartPane,
   normalizeRemote,
+  normalizeGateQuestions,
+  normalizeGateOptions,
   listTeams,
   listSettings,
   listRuns,
@@ -2315,12 +2415,14 @@ export {
   gateUnsubscribe,
   gateSubscriptions,
   gateSubscribe,
+  gatePresentation,
   gatePark,
   gateOptionValue,
   gateOptionLabel,
   gateOpen,
   gateList,
   gateClose,
+  gateAsk,
   gateAnswer,
   formatPaneRef,
   explainSetting,
@@ -2366,6 +2468,7 @@ export {
   abandonRun,
   SCOPE_ORDER,
   REGISTRY,
+  GATE_FORM_OPTION_CAP,
   GATE_BY_PANE,
   DEFAULT_WS_URL,
   DEFAULT_SOCK,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.20.0",
+  "version": "0.23.0",
   "type": "module",
   "exports": {
     ".": {

package/src/client.ts

@@ -472,6 +472,15 @@ export function gateOpen(
   return rtCommand<Commands["gate:open"]["data"]>("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
+export function gateAsk(
+  a: Commands["gate:ask"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["gate:ask"]["data"]>> {
+  const payload: Record<string, unknown> = { questions: a.questions };
+  for (const k of ["context", "kind", "subject", "sessionId", "paneId", "meta", "agent", "origin"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["gate:ask"]["data"]>("gate:ask", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
 export function gateAnswer(
   a: Commands["gate:answer"]["payload"],
   o: RtClientOptions = {},
@@ -586,7 +595,8 @@ export function herdAnswer(
   a: Commands["herd:answer"]["payload"],
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["herd:answer"]["data"]>> {
-  return rtCommand<Commands["herd:answer"]["data"]>("herd:answer", { gate: a.gate }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  const payload = { gate: a.gate, ...(a.sessionId !== undefined ? { sessionId: a.sessionId } : {}) };
+  return rtCommand<Commands["herd:answer"]["data"]>("herd:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 /** A disposable job's report also closes its pane, one herdr CLI call under the runner's own 15s budget. */

package/src/commands.ts

@@ -97,12 +97,13 @@ export const GATE_BY_PANE = "pane";
 export type GateStatus = "open" | "answered" | "parked" | "closed";
 /** Reconciler's view of an agent's liveness; also the value `GateRow.executor` is stamped with. */
 export type ExecutorState = "live" | "blocked" | "hidden" | "gone" | "cleared" | "unknown";
-export type GateOption = string | { value: string; label: string };
+export type GateOption = string | { value: string; label: string; recommended?: boolean };
 export interface GateOrigin {
   paneId?: string;
   tabId?: string;
   runId?: string;
   worktree?: string;
+  surface?: string;
   presentation?: "form" | "wait";
 }
 export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[] }
@@ -112,7 +113,12 @@ export function gateOptionValue(o: GateOption): string {
 export function gateOptionLabel(o: GateOption): string {
   return typeof o === "string" ? o : (o.label || o.value);
 }
-export interface GateAnswer { answers: Record<string, string | string[] | { value: string | string[]; note?: string }>; by: string; answeredAt: number; overridden?: boolean }
+/** `session` is the answering surface's own session id, recorded so the
+    push facility can tell a self-answer from a remote one and skip the
+    doorbell it would otherwise send back to the writer. Optional: a caller
+    that supplies none (the board status-bin answers `by: "pane"` with no
+    session) still matches self by `by === GATE_BY_PANE`. */
+export interface GateAnswer { answers: Record<string, string | string[] | { value: string | string[]; note?: string }>; by: string; answeredAt: number; overridden?: boolean; session?: string }
 export interface GateRow {
   id: string; subject: string; kind: string;
   questions: GateQuestion[]; meta: Record<string, unknown> | null;
@@ -130,6 +136,15 @@ export interface GateRow {
   nudge: { session: string } | null;
   delivery: { outcome: "delivered" | "dead-pane" | "confirmed" | "stuck"; at: number } | null;
   released: boolean;
+  /** Set once the nudged pane has provably read the answer: either it
+      self-answered (stamped in the same transaction as the answer) or a
+      later `markConsumed` call recorded that it acted on a push. `null`
+      until then, so a sweep can tell an answered-but-unread row from a
+      settled one. Currently only stamped for herd-subject gates (the
+      self-answer path and `rt herd answer`'s nudged-session read); a
+      non-herd gate with a nudge stays `null` even after its pane
+      reconciles. */
+  consumedAt: number | null;
   owner: string | null;
   escalatedAt: number | null;
   /** Set by answer-time execution handling: an answered gate whose executor
@@ -154,10 +169,10 @@ export interface HerdInfo { id: string; repo: string; room: string; workspace: s
 /** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
 export interface HerdListRow extends HerdInfo { jobs: number }
 export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. */
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
   herd: HerdInfo;
-  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null }>;
+  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
   unread: number;
   lifecycleConnected: boolean;
   hiddenUp: boolean | null;
@@ -642,6 +657,18 @@ export interface Commands {
   "discussions:reply": { payload: { repoName: string; iid: number; discussionId: string; body: string }; data: DiscussionsWriteData };
   "discussions:diffs": { payload: { repoName: string; iid: number }; data: DiscussionsDiffsData };
 
+  /** Positioned inline MR comment with server-side DiffNote verification:
+      posts, re-checks the created note's type from the creation response,
+      and on the silent general-note degrade deletes the stray note and
+      retries ONCE with freshly fetched diff_refs. The retry repairs only
+      the stale-diff-refs degrade; a caller-supplied position GitLab
+      rejects stays rejected, and after a second degrade both stray notes
+      are deleted and the call fails. `verified: true` means the check ran. */
+  "mr:comment-inline": {
+    payload: { repoName: string; iid: number; body: string; path: string; line: number; oldPath?: string; oldLine?: number };
+    data: { discussionId: string; noteId: number; verified: true };
+  };
+
   /** Wire reply is `{ok:true}` on success (no `data`); a failure is `{ok:false,error}`. */
   "mr:action": { payload: { repoName: string; iid: number; action: MRActionName; args?: unknown[] }; data: Record<string, never> };
   "mr:fetch-job-detail": { payload: { repoName: string; iid: number; jobId: number; pipelineId?: number }; data: MrJobDetail };
@@ -663,6 +690,32 @@ export interface Commands {
 
   // ─── Gate facility (BOARD-20/21) ─────────────────────────────────────────
   "gate:open": { payload: { subject: string; kind: string; questions: GateQuestion[]; meta?: Record<string, unknown>; agent?: string; pane?: string; nudge?: { session: string }; context?: string; origin?: GateOrigin }; data: { id: string; supersededId: string | null } };
+  /** Ceremony layer over gate:open: resolves subject from the caller's
+      session (an explicit subject always wins as the subject, but still
+      picks up run linkage from the session's own running run; else its
+      single running run as `run:<id>`; else its agent record's recorded
+      subject, or `agent:<id>` when it has none), computes
+      presentation via gatePresentation, supplies nudge/origin, and omits an
+      oversized context instead of rejecting it. `meta` and `agent` forward
+      to gate:open verbatim; `origin` passthrough fields fill gaps in the
+      ceremony's own origin (presentation, paneId, runId, run-derived
+      worktree always win over a caller-supplied value for the same key).
+      Delegates to gate:open for everything else (validation, supersede,
+      events, push). */
+  "gate:ask": {
+    payload: {
+      questions: GateQuestion[];
+      context?: string;
+      kind?: string;
+      subject?: string;
+      sessionId?: string;
+      paneId?: string;
+      meta?: Record<string, unknown>;
+      agent?: string;
+      origin?: { surface?: string; tabId?: string; worktree?: string };
+    };
+    data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null };
+  };
   /**
    * A CAS loss is a DEFINED OUTCOME, not an error: `ok:true` with
    * `conflict:true` and the WINNING row, so every consumer gets the winner
@@ -703,7 +756,7 @@ export interface Commands {
   "herd:gates":  { payload: { herd: string }; data: { gates: GateRow[] } };
   "herd:ask":       { payload: { herd: string; job: string; session: string; pane?: string; questions: GateQuestion[]; context?: string }; data: { gate: string } };
   "herd:milestone": { payload: { herd: string; job: string; session: string; pane?: string; artifact: string; summary?: string }; data: { gate: string; message: number } };
-  "herd:answer":    { payload: { gate: string }; data: { gate: string; status: GateStatus; answer: GateAnswer | null; closedReason: GateRow["closedReason"] } };
+  "herd:answer":    { payload: { gate: string; sessionId?: string }; data: { gate: string; status: GateStatus; answer: GateAnswer | null; closedReason: GateRow["closedReason"] } };
   "herd:report":    { payload: { herd: string; job: string; body: string }; data: { message: number } };
   /** `callerWorkspace` is the attending session's own HERDR_WORKSPACE_ID: the attached tab opens there, not in the herd's workspace. */
   "herd:attend":      { payload: { herd: string; job: string; callerWorkspace: string }; data: { tab: string; pane: string } };
@@ -802,6 +855,7 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "discussions:resolve",
   "discussions:reply",
   "discussions:diffs",
+  "mr:comment-inline",
   "mr:action",
   "mr:fetch-job-detail",
   "mr:fetch-job-trace",
@@ -814,6 +868,7 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "reconciler:status",
   "reconciler:clear",
   "gate:open",
+  "gate:ask",
   "gate:answer",
   "gate:wait",
   "gate:list",

package/src/gate-answers.ts

@@ -0,0 +1,54 @@
+import type { GateQuestion, GateAnswer } from "./commands.ts";
+import { gateOptionValue } from "./commands.ts";
+
+export type GateAnswerWire = GateAnswer["answers"][string];
+
+/** Both wire shapes carry the same value underneath: bare, or {value, note?}
+    when a panel attaches free text. Validation reads only the value. */
+export function unwrapGateAnswerValue(raw: unknown): unknown {
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && "value" in (raw as Record<string, unknown>)) {
+    return (raw as { value: unknown }).value;
+  }
+  return raw;
+}
+
+function wrapperNoteIsValid(raw: unknown): boolean {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !("value" in (raw as Record<string, unknown>))) {
+    return true;
+  }
+  const note = (raw as Record<string, unknown>).note;
+  return note === undefined || typeof note === "string";
+}
+
+/** Option membership is required whenever a question declares options,
+    checked against the unwrapped value (every element, for multi); an
+    empty options array stays free-form. Every question id must appear as
+    an answers key. Error strings are a wire contract; packages/rt-client/test/gate-answers.test.ts pins them verbatim. */
+export function validateGateAnswers(
+  questions: GateQuestion[],
+  answers: Record<string, unknown>,
+): string | null {
+  const byId = new Map(questions.map((q) => [q.id, q]));
+  for (const [qid, raw] of Object.entries(answers)) {
+    const question = byId.get(qid);
+    if (!question) return `unknown question id: ${qid}`;
+    if (!wrapperNoteIsValid(raw)) return `question ${qid} note must be a string`;
+    const value = unwrapGateAnswerValue(raw);
+    const isArray = Array.isArray(value);
+    if (question.multi && !isArray) return `question ${qid} expects an array (multi)`;
+    if (!question.multi && isArray) return `question ${qid} expects a single value`;
+    const values = isArray ? (value as unknown[]) : [value];
+    if (!values.every((v) => typeof v === "string")) return `question ${qid} value must be a string`;
+    if (question.options.length > 0) {
+      const members = question.options.map(gateOptionValue);
+      for (const v of values as string[]) {
+        if (!members.includes(v)) return `answer for "${qid}" is not one of its options: "${v}"`;
+      }
+    }
+  }
+  const missing = questions
+    .map((q) => q.id)
+    .filter((id) => !Object.prototype.hasOwnProperty.call(answers, id));
+  if (missing.length > 0) return `missing answer(s) for: ${missing.join(", ")}`;
+  return null;
+}

package/src/gate-options.ts

@@ -0,0 +1,72 @@
+import type { GateOption, GateQuestion } from "./commands.ts";
+
+/** The canonical stored/emitted option shape (contract C11). GateOption
+    (the input union) is unchanged; rows normalized by the daemon always
+    satisfy this. */
+export interface GateOptionObject {
+  value: string;
+  label: string;
+}
+
+/** Suffix gate-kit's stripRecommended (mattstack-apps repo,
+    packages/gate-kit/src/options.ts) parses off a label to render its own
+    "recommended" badge. This is the
+    wire representation of `recommended: true` -- the flag itself never
+    reaches the normalized output. */
+const RECOMMENDED_SUFFIX = " (Recommended)";
+const HAS_RECOMMENDED_SUFFIX = /\(\s*recommended\s*\)\s*$/i;
+
+/** A label is word-like -- eligible for auto-capitalization -- only when it
+    starts with a lowercase ASCII letter, has no digit/`/`/`:`/`\`/`@`
+    anywhere (those mark paths, ids, and verb:token pairs that must not be
+    reworded), and has no uppercase letter already (mixed-case labels like
+    "gitLab" are left as the caller spelled them). */
+function isWordLikeLabel(label: string): boolean {
+  return /^[a-z][^A-Z0-9/:\\@]*$/.test(label);
+}
+
+function capitalize(label: string): string {
+  return isWordLikeLabel(label) ? label[0]!.toUpperCase() + label.slice(1) : label;
+}
+
+/** Bare string s becomes {value: s, label: s}; a well-formed {value,label}
+    object passes through untouched. Total over whatever actually arrives
+    on the wire, not just the declared GateOption union: a partial object
+    fills the missing field from the one present, and anything else
+    (null, a number, an object with neither field) is coerced via String()
+    into both fields. The resulting label is then capitalized when
+    word-like (see isWordLikeLabel), and an object form's `recommended:
+    true` lifts into a " (Recommended)" label suffix -- guarded against
+    double-appending -- since `recommended` itself does not survive into
+    the returned object; the suffix IS its wire representation. Every
+    returned entry is a full {value,label} pair -- callers may trust the
+    return type without re-checking it. Pure and order-preserving. */
+export function normalizeGateOptions(options: GateOption[]): GateOptionObject[] {
+  return options.map((o) => {
+    const recommended = o !== null && typeof o === "object" && (o as { recommended?: unknown }).recommended === true;
+    let value: string;
+    let label: string;
+    if (typeof o === "string") {
+      value = o;
+      label = o;
+    } else if (o !== null && typeof o === "object") {
+      const v = typeof (o as { value?: unknown }).value === "string" ? (o as { value: string }).value : undefined;
+      const l = typeof (o as { label?: unknown }).label === "string" ? (o as { label: string }).label : undefined;
+      value = v ?? l ?? String(o);
+      label = l ?? v ?? String(o);
+    } else {
+      value = String(o);
+      label = String(o);
+    }
+    label = capitalize(label);
+    // An empty label stays empty rather than becoming just the suffix: a
+    // downstream `label || value` fallback (gate-kit) must still see label
+    // as absent, not as a non-empty "(Recommended)" that hides the value.
+    if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label)) label += RECOMMENDED_SUFFIX;
+    return { value, label };
+  });
+}
+
+export function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[] {
+  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+}

package/src/gate-presentation.ts

@@ -0,0 +1,17 @@
+import type { GateQuestion } from "./commands.ts";
+
+export const GATE_FORM_OPTION_CAP = 4;
+
+/** The ONE presentation rule (spec Phase 1): form iff an injectable pane
+    exists, a nudge target exists, and every question fits the native form's
+    per-question option cap. */
+export function gatePresentation(args: {
+  paneId?: string | undefined;
+  sessionId?: string | undefined;
+  questions: GateQuestion[];
+}): "form" | "wait" {
+  if (!args.paneId || !args.sessionId) return "wait";
+  return args.questions.every((q) => q.options.length <= GATE_FORM_OPTION_CAP)
+    ? "form"
+    : "wait";
+}

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   reconcilerStatus,
   reconcilerClear,
   gateOpen,
+  gateAsk,
   gateAnswer,
   gateWait,
   gateList,
@@ -77,6 +78,11 @@ export {
 } from "./client.ts";
 
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
+export { GATE_FORM_OPTION_CAP, gatePresentation } from "./gate-presentation.ts";
+export { normalizeGateOptions, normalizeGateQuestions } from "./gate-options.ts";
+export type { GateOptionObject } from "./gate-options.ts";
+export { unwrapGateAnswerValue, validateGateAnswers } from "./gate-answers.ts";
+export type { GateAnswerWire } from "./gate-answers.ts";
 export type {
   Discussion,
   DemandDecl,

package/src/settings/registry-defs.ts

@@ -85,7 +85,7 @@ export const REGISTRY: readonly SettingDef[] = [
     scopes: ["user"],
     default: [],
     merge: "replace",
-    description: "Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message, subjectPrefix?, url?, owner?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload's first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload's subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification's Open target; a gate rule should set it. The optional owner field (only literal \"human\" is valid) suppresses events whose payload.owner starts with \"herd:\", allowing gate rules to skip herd-owned events. A typical setup pairs a gate/opened rule with owner: \"human\" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A fresh key, not an ownership-latch port, so a default is fine here.",
+    description: "Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message, subjectPrefix?, url?, owner?, surface?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload's first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload's subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification's Open target; a gate rule should set it. The optional owner field (only literal \"human\" is valid) suppresses events whose payload.owner starts with \"herd:\", allowing gate rules to skip herd-owned events. The optional surface field (a string) matches only events whose payload.origin.surface equals the given value, allowing a rule to fire only for gates opened by a specific surface (e.g. surface: \"board\" matches only board-originated gates). A typical setup pairs a gate/opened rule with owner: \"human\" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A board-specific rule can combine surface: \"board\" with a board URL to open the decision queue directly. A fresh key, not an ownership-latch port, so a default is fine here.",
   },
   {
     key: "rt.cron",