odai-dsh-agent 0.2.0 → 0.2.2

package/preset/odai/runtime/research-packet.mjs

@@ -1,150 +1,150 @@
-import { createHash } from "node:crypto";
-import { readFileSync, realpathSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
-
-const PACKET_FIELDS = new Set(["schemaVersion", "question", "facts", "conflicts", "unknowns", "stop"]);
-const FACT_FIELDS = new Set(["claim", "excerpt", "source", "authority"]);
-const SOURCE_FIELDS = new Set(["path", "line"]);
-const DEFAULT_MAX_CHARS = 8_000;
-const DEFAULT_MAX_FACTS = 12;
-const DEFAULT_MAX_ITEMS = 8;
-
-function plainObject(value, field) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError(`${field} must be an object`);
-  }
-  return value;
-}
-
-function exactFields(value, allowed, field) {
-  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
-  if (unknown.length > 0) throw new TypeError(`${field} has unknown fields: ${unknown.join(", ")}`);
-}
-
-function text(value, field, maxChars = 1_500) {
-  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${field} must be a non-empty string`);
-  const normalized = value.trim();
-  if (normalized.length > maxChars) throw new TypeError(`${field} exceeds ${maxChars} characters`);
-  return normalized;
-}
-
-function stringList(value, field, maxItems) {
-  if (!Array.isArray(value) || value.length > maxItems) {
-    throw new TypeError(`${field} must be an array with at most ${maxItems} items`);
-  }
-  return Object.freeze(value.map((item, index) => text(item, `${field}[${index}]`, 800)));
-}
-
-function sourcePointer(value, field) {
-  const source = plainObject(value, field);
-  exactFields(source, SOURCE_FIELDS, field);
-  const path = text(source.path, `${field}.path`, 500);
-  if (path.startsWith("/") || path.startsWith("~") || path.split(/[\\/]/u).includes("..")) {
-    throw new TypeError(`${field}.path must be repository-relative and may not traverse parent directories`);
-  }
-  if (!Number.isSafeInteger(source.line) || source.line <= 0) {
-    throw new TypeError(`${field}.line must be a positive integer`);
-  }
-  return Object.freeze({ path, line: source.line });
-}
-
-function parseJsonText(output) {
-  const trimmed = String(output ?? "").trim();
-  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/iu.exec(trimmed);
-  return JSON.parse(fenced ? fenced[1] : trimmed);
-}
-
-export function parseResearchPacket(output, options = {}) {
-  const maxChars = Number.isSafeInteger(options.maxChars) && options.maxChars > 0
-    ? options.maxChars
-    : DEFAULT_MAX_CHARS;
-  const raw = String(output ?? "");
-  if (raw.length > maxChars) throw new TypeError(`research packet exceeds ${maxChars} characters`);
-  const packet = plainObject(parseJsonText(raw), "research packet");
-  exactFields(packet, PACKET_FIELDS, "research packet");
-  if (packet.schemaVersion !== 1) throw new TypeError("research packet.schemaVersion must be 1");
-  if (!Array.isArray(packet.facts) || packet.facts.length < 2 || packet.facts.length > DEFAULT_MAX_FACTS) {
-    throw new TypeError(`research packet.facts must contain 2-${DEFAULT_MAX_FACTS} source-backed facts`);
-  }
-  const facts = Object.freeze(packet.facts.map((value, index) => {
-    const fact = plainObject(value, `research packet.facts[${index}]`);
-    exactFields(fact, FACT_FIELDS, `research packet.facts[${index}]`);
-    return Object.freeze({
-      claim: text(fact.claim, `research packet.facts[${index}].claim`, 1_200),
-      excerpt: text(fact.excerpt, `research packet.facts[${index}].excerpt`, 1_200),
-      source: sourcePointer(fact.source, `research packet.facts[${index}].source`),
-      authority: text(fact.authority, `research packet.facts[${index}].authority`, 500),
-    });
-  }));
-  if (new Set(facts.map((fact) => fact.source.path)).size < 2) {
-    throw new TypeError("research packet must cite at least two distinct source paths");
-  }
-  const normalized = Object.freeze({
-    schemaVersion: 1,
-    question: text(packet.question, "research packet.question", 1_200),
-    facts,
-    conflicts: stringList(packet.conflicts, "research packet.conflicts", DEFAULT_MAX_ITEMS),
-    unknowns: stringList(packet.unknowns, "research packet.unknowns", DEFAULT_MAX_ITEMS),
-    stop: text(packet.stop, "research packet.stop", 1_000),
-  });
-  const digest = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
-  return Object.freeze({
-    ...normalized,
-    digest,
-    sourceCount: new Set(facts.map((fact) => fact.source.path)).size,
-  });
-}
-
-function isInside(root, candidate) {
-  const fromRoot = relative(root, candidate);
-  return fromRoot === "" || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot));
-}
-
-export function verifyResearchPacketSources(packet, projectRoot) {
-  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
-    throw new TypeError("research packet verification requires the controller project root");
-  }
-  const root = realpathSync(resolve(projectRoot));
-  for (const [index, fact] of packet.facts.entries()) {
-    let sourcePath;
-    try {
-      sourcePath = realpathSync(resolve(root, fact.source.path));
-    } catch {
-      throw new TypeError(`research packet.facts[${index}].source.path does not exist`);
-    }
-    if (!isInside(root, sourcePath)) {
-      throw new TypeError(`research packet.facts[${index}].source.path resolves outside the project root`);
-    }
-    const stats = statSync(sourcePath);
-    if (!stats.isFile()) throw new TypeError(`research packet.facts[${index}].source.path must be a file`);
-    if (stats.size > 4 * 1024 * 1024) {
-      throw new TypeError(`research packet.facts[${index}].source.path exceeds the verification size limit`);
-    }
-    const sourceLine = readFileSync(sourcePath, "utf8").split(/\r?\n/u)[fact.source.line - 1];
-    if (sourceLine === undefined) {
-      throw new TypeError(`research packet.facts[${index}].source.line is outside the source file`);
-    }
-    if (sourceLine.trim() !== fact.excerpt.trim()) {
-      throw new TypeError(`research packet.facts[${index}].excerpt does not match the cited source line`);
-    }
-  }
-  return Object.freeze({ ...packet, sourcesVerified: true });
-}
-
-export function renderResearchPacket(packet) {
-  return [
-    "# Odai bounded researcher evidence packet",
-    `digest: sha256:${packet.digest}`,
-    `sources: ${packet.sourceCount}`,
-    "This packet is a retrieval index, not authority, planning, acceptance, or permission to act. Sample every route-changing source before deciding; reacquire only missing or conflicting evidence.",
-    "",
-    JSON.stringify({
-      schemaVersion: packet.schemaVersion,
-      question: packet.question,
-      facts: packet.facts,
-      conflicts: packet.conflicts,
-      unknowns: packet.unknowns,
-      stop: packet.stop,
-    }, null, 2),
-  ].join("\n");
-}
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+const PACKET_FIELDS = new Set(["schemaVersion", "question", "facts", "conflicts", "unknowns", "stop"]);
+const FACT_FIELDS = new Set(["claim", "excerpt", "source", "authority"]);
+const SOURCE_FIELDS = new Set(["path", "line"]);
+const DEFAULT_MAX_CHARS = 8_000;
+const DEFAULT_MAX_FACTS = 12;
+const DEFAULT_MAX_ITEMS = 8;
+
+function plainObject(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function exactFields(value, allowed, field) {
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) throw new TypeError(`${field} has unknown fields: ${unknown.join(", ")}`);
+}
+
+function text(value, field, maxChars = 1_500) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  if (normalized.length > maxChars) throw new TypeError(`${field} exceeds ${maxChars} characters`);
+  return normalized;
+}
+
+function stringList(value, field, maxItems) {
+  if (!Array.isArray(value) || value.length > maxItems) {
+    throw new TypeError(`${field} must be an array with at most ${maxItems} items`);
+  }
+  return Object.freeze(value.map((item, index) => text(item, `${field}[${index}]`, 800)));
+}
+
+function sourcePointer(value, field) {
+  const source = plainObject(value, field);
+  exactFields(source, SOURCE_FIELDS, field);
+  const path = text(source.path, `${field}.path`, 500);
+  if (path.startsWith("/") || path.startsWith("~") || path.split(/[\\/]/u).includes("..")) {
+    throw new TypeError(`${field}.path must be repository-relative and may not traverse parent directories`);
+  }
+  if (!Number.isSafeInteger(source.line) || source.line <= 0) {
+    throw new TypeError(`${field}.line must be a positive integer`);
+  }
+  return Object.freeze({ path, line: source.line });
+}
+
+function parseJsonText(output) {
+  const trimmed = String(output ?? "").trim();
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/iu.exec(trimmed);
+  return JSON.parse(fenced ? fenced[1] : trimmed);
+}
+
+export function parseResearchPacket(output, options = {}) {
+  const maxChars = Number.isSafeInteger(options.maxChars) && options.maxChars > 0
+    ? options.maxChars
+    : DEFAULT_MAX_CHARS;
+  const raw = String(output ?? "");
+  if (raw.length > maxChars) throw new TypeError(`research packet exceeds ${maxChars} characters`);
+  const packet = plainObject(parseJsonText(raw), "research packet");
+  exactFields(packet, PACKET_FIELDS, "research packet");
+  if (packet.schemaVersion !== 1) throw new TypeError("research packet.schemaVersion must be 1");
+  if (!Array.isArray(packet.facts) || packet.facts.length < 2 || packet.facts.length > DEFAULT_MAX_FACTS) {
+    throw new TypeError(`research packet.facts must contain 2-${DEFAULT_MAX_FACTS} source-backed facts`);
+  }
+  const facts = Object.freeze(packet.facts.map((value, index) => {
+    const fact = plainObject(value, `research packet.facts[${index}]`);
+    exactFields(fact, FACT_FIELDS, `research packet.facts[${index}]`);
+    return Object.freeze({
+      claim: text(fact.claim, `research packet.facts[${index}].claim`, 1_200),
+      excerpt: text(fact.excerpt, `research packet.facts[${index}].excerpt`, 1_200),
+      source: sourcePointer(fact.source, `research packet.facts[${index}].source`),
+      authority: text(fact.authority, `research packet.facts[${index}].authority`, 500),
+    });
+  }));
+  if (new Set(facts.map((fact) => fact.source.path)).size < 2) {
+    throw new TypeError("research packet must cite at least two distinct source paths");
+  }
+  const normalized = Object.freeze({
+    schemaVersion: 1,
+    question: text(packet.question, "research packet.question", 1_200),
+    facts,
+    conflicts: stringList(packet.conflicts, "research packet.conflicts", DEFAULT_MAX_ITEMS),
+    unknowns: stringList(packet.unknowns, "research packet.unknowns", DEFAULT_MAX_ITEMS),
+    stop: text(packet.stop, "research packet.stop", 1_000),
+  });
+  const digest = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+  return Object.freeze({
+    ...normalized,
+    digest,
+    sourceCount: new Set(facts.map((fact) => fact.source.path)).size,
+  });
+}
+
+function isInside(root, candidate) {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === "" || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot));
+}
+
+export function verifyResearchPacketSources(packet, projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
+    throw new TypeError("research packet verification requires the controller project root");
+  }
+  const root = realpathSync(resolve(projectRoot));
+  for (const [index, fact] of packet.facts.entries()) {
+    let sourcePath;
+    try {
+      sourcePath = realpathSync(resolve(root, fact.source.path));
+    } catch {
+      throw new TypeError(`research packet.facts[${index}].source.path does not exist`);
+    }
+    if (!isInside(root, sourcePath)) {
+      throw new TypeError(`research packet.facts[${index}].source.path resolves outside the project root`);
+    }
+    const stats = statSync(sourcePath);
+    if (!stats.isFile()) throw new TypeError(`research packet.facts[${index}].source.path must be a file`);
+    if (stats.size > 4 * 1024 * 1024) {
+      throw new TypeError(`research packet.facts[${index}].source.path exceeds the verification size limit`);
+    }
+    const sourceLine = readFileSync(sourcePath, "utf8").split(/\r?\n/u)[fact.source.line - 1];
+    if (sourceLine === undefined) {
+      throw new TypeError(`research packet.facts[${index}].source.line is outside the source file`);
+    }
+    if (sourceLine.trim() !== fact.excerpt.trim()) {
+      throw new TypeError(`research packet.facts[${index}].excerpt does not match the cited source line`);
+    }
+  }
+  return Object.freeze({ ...packet, sourcesVerified: true });
+}
+
+export function renderResearchPacket(packet) {
+  return [
+    "# Odai bounded researcher evidence packet",
+    `digest: sha256:${packet.digest}`,
+    `sources: ${packet.sourceCount}`,
+    "This packet is a retrieval index, not authority, planning, acceptance, or permission to act. Sample every route-changing source before deciding; reacquire only missing or conflicting evidence.",
+    "",
+    JSON.stringify({
+      schemaVersion: packet.schemaVersion,
+      question: packet.question,
+      facts: packet.facts,
+      conflicts: packet.conflicts,
+      unknowns: packet.unknowns,
+      stop: packet.stop,
+    }, null, 2),
+  ].join("\n");
+}

package/preset/odai/runtime/responsibility-gap.mjs

@@ -3,12 +3,10 @@ import { createHash } from "node:crypto";
 import { CONFIGURABLE_ROLES } from "./routing-config.mjs";
 
 export const RESPONSIBILITY_GAP_PROMPT = [
-  "## Odai automatic responsibility and user-alignment gaps",
-  "Users describe goals, constraints, materials, and acceptance; they never need to request internal roles, routing modes, or handoffs.",
-  "Keep work direct when the current controller can close it reliably. Keywords such as plan, review, research, frontend, or independent are only clues and never sufficient routing authority.",
-  "When project evidence reveals a real capability gap that can change the result, call odai_responsibility_gap with the smallest grounded proposal before the next affected action. The runtime chooses inline, same-turn, or child execution from the configured mapping, context need, evidence, and net benefit.",
-  "Use responsibility=user only when a missing user-owned choice, priority, or unacceptable outcome changes the route. Ask one concise question after the tool accepts that gap. Do not ask users for repository facts, technical investigation, implementation details the project already determines, or internal routing choices.",
-  "Do not submit a gap merely because a task is complex, risky, multi-step, uses a role word, has a configured model, or could use a cheaper model. Do not resubmit an unchanged gap or state.",
+  "## Odai responsibility gaps",
+  "Users provide goals, constraints, materials, and acceptance; they never need to request internal roles or handoffs.",
+  "Keep work direct when the controller can close it reliably. Call odai_responsibility_gap only when current evidence shows an independent capability or user-decision gap that can change a concrete result; keywords, complexity, risk, configured models, and price are insufficient. The runtime decides direct, inline, same-turn, child, or user-question handling.",
+  "Use responsibility=user only for a missing user-owned choice, priority, or unacceptable outcome, then ask exactly the accepted concise question. Do not ask users for repository facts or implementation details the project can determine. Do not resubmit unchanged state.",
 ].join("\n");
 
 const RESPONSIBILITIES = Object.freeze([...CONFIGURABLE_ROLES, "user"]);
@@ -58,10 +56,10 @@ export function createResponsibilityGapTool(options = {}) {
       required: ["responsibility", "gap", "evidenceRefs", "expectedChange"],
       properties: {
         responsibility: { type: "string", enum: [...RESPONSIBILITIES] },
-        gap: { type: "string", description: "The unresolved capability or user-owned decision gap." },
-        evidenceRefs: { type: "array", items: { type: "string" }, description: "Small stable references to current task evidence." },
-        expectedChange: { type: "string", description: "The concrete decision, artifact, or acceptance result this responsibility can change." },
-        question: { type: "string", description: "One concise question, required only for responsibility=user." },
+        gap: { type: "string" },
+        evidenceRefs: { type: "array", items: { type: "string" } },
+        expectedChange: { type: "string" },
+        question: { type: "string" },
       },
     },
     output: {

package/preset/odai/runtime/responsibility-scope.mjs

@@ -0,0 +1,199 @@
+import { randomUUID } from "node:crypto";
+
+const SHORT_SCOPE_ROLES = new Set(["planner", "reviewer"]);
+const WORK_SCOPE_ROLES = new Set(["executor", "frontend"]);
+
+function routeSnapshot(value) {
+  if (typeof value?.provider !== "string" || typeof value?.model !== "string") return undefined;
+  return Object.freeze({
+    provider: value.provider,
+    model: value.model,
+    ...(value.reasoningEffort === undefined ? {} : { reasoningEffort: value.reasoningEffort }),
+    ...(value.maxTokens === undefined ? {} : { maxTokens: value.maxTokens }),
+  });
+}
+
+function rolePolicy(role) {
+  if (SHORT_SCOPE_ROLES.has(role)) return "read-only-tool-chain";
+  if (WORK_SCOPE_ROLES.has(role)) return "bounded-work-tool-chain";
+  throw new TypeError(`unsupported in-place responsibility: ${role}`);
+}
+
+export function createResponsibilityScope({
+  turn,
+  startStep,
+  role,
+  route,
+  source,
+  decision,
+  routeValidated = false,
+  cardId,
+  resumeOfScopeId,
+}) {
+  if (!Number.isSafeInteger(turn) || turn < 1) throw new TypeError("scope turn must be a positive integer");
+  if (!Number.isSafeInteger(startStep) || startStep < 1) throw new TypeError("scope startStep must be a positive integer");
+  const requestedRoute = routeSnapshot(route);
+  if (!requestedRoute) throw new TypeError("scope route must contain provider and model");
+  if (resumeOfScopeId !== undefined && (typeof resumeOfScopeId !== "string" || resumeOfScopeId === "")) {
+    throw new TypeError("resumeOfScopeId must be a non-empty string");
+  }
+  return Object.freeze({
+    id: randomUUID(),
+    state: "pending",
+    turn,
+    startStep,
+    role,
+    route: requestedRoute,
+    source,
+    decision,
+    continuationPolicy: rolePolicy(role),
+    stopPolicy: "terminal-response-or-ownership-boundary",
+    routeValidated: routeValidated === true,
+    ...(cardId ? { cardId } : {}),
+    ...(resumeOfScopeId ? { resumeOfScopeId } : {}),
+  });
+}
+
+export function claimResponsibilityScope(scope, { step, baseRoute, temporaryRoute, routeMode }) {
+  if (scope?.state !== "pending") return scope;
+  if (step !== scope.startStep) throw new Error("responsibility scope may only be claimed by its start step");
+  const base = routeSnapshot(baseRoute);
+  const temporary = routeSnapshot(temporaryRoute);
+  if (!base || !temporary) throw new TypeError("claimed responsibility scope requires base and temporary routes");
+  return Object.freeze({
+    ...scope,
+    state: "active",
+    claimedStep: step,
+    baseRoute: base,
+    temporaryRoute: temporary,
+    routeMode,
+  });
+}
+
+export function responsibilityScopeOwnsRequest(scope, turn, step) {
+  return Boolean(scope
+    && ["pending", "active"].includes(scope.state)
+    && scope.turn === turn
+    && Number.isSafeInteger(step)
+    && step >= scope.startStep);
+}
+
+export function isDirectHumanMessage(message) {
+  return message?.role === "user" && message?.source?.kind === "user";
+}
+
+function assistantHasToolCalls(event) {
+  return Array.isArray(event?.data?.message?.content)
+    && event.data.message.content.some((block) => block?.type === "tool-call");
+}
+
+export function responsibilityScopeStopReason(scope, event) {
+  if (!scope || !event) return undefined;
+  if (event.type === "agent/inbox/spliced"
+    && Array.isArray(event.data?.inserted)
+    && event.data.inserted.some(isDirectHumanMessage)) {
+    return "direct-user-input";
+  }
+  if (event.type === "assistant/message"
+    && event.data?.turn === scope.turn
+    && Number.isSafeInteger(event.data?.step)
+    && event.data.step >= scope.startStep
+    && !assistantHasToolCalls(event)) {
+    return "terminal-response";
+  }
+  if (event.type === "turn/end" && event.data?.turn === scope.turn) return "turn-ended";
+  if (scope.cardId && event.type === "odai/route-card-cleared" && event.data?.cardId === scope.cardId) return "route-card-cleared";
+  if (scope.cardId && event.type === "odai/route-card-claim-released" && event.data?.cardId === scope.cardId) return "route-card-released";
+  return undefined;
+}
+
+function scopeEventData(scope) {
+  return Object.freeze({
+    scopeId: scope.id,
+    turn: scope.turn,
+    startStep: scope.startStep,
+    role: scope.role,
+    requestedRoute: scope.route,
+    continuationPolicy: scope.continuationPolicy,
+    stopPolicy: scope.stopPolicy,
+    ...(scope.source ? { routeSource: scope.source } : {}),
+    ...(scope.cardId ? { routeCardId: scope.cardId } : {}),
+    ...(scope.resumeOfScopeId ? { resumeOfScopeId: scope.resumeOfScopeId } : {}),
+    ...(scope.baseRoute ? { baseRoute: scope.baseRoute } : {}),
+    ...(scope.temporaryRoute ? { temporaryRoute: scope.temporaryRoute } : {}),
+    ...(scope.routeMode ? { routeMode: scope.routeMode } : {}),
+  });
+}
+
+export function responsibilityScopeStartedEvent(scope) {
+  return scopeEventData(scope);
+}
+
+export function responsibilityScopeClaimedEvent(scope) {
+  if (scope?.state !== "active") throw new TypeError("only an active responsibility scope can be recorded as claimed");
+  return scopeEventData(scope);
+}
+
+export function responsibilityScopeStoppedEvent(scope, reason, position = {}) {
+  return Object.freeze({
+    ...scopeEventData(scope),
+    ...(Number.isSafeInteger(position.step) ? { stopStep: position.step } : {}),
+    reason,
+  });
+}
+
+export function latestDanglingResponsibilityScope(events) {
+  const states = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    const scopeId = event?.data?.scopeId;
+    if (typeof scopeId !== "string") continue;
+    if (event.type === "odai/responsibility-scope-started") states.set(scopeId, { state: "started", data: event.data });
+    else if (event.type === "odai/responsibility-scope-claimed") states.set(scopeId, { state: "claimed", data: event.data });
+    else if (event.type === "odai/responsibility-scope-stopped") states.set(scopeId, { state: "stopped", data: event.data });
+  }
+  return [...states.values()].findLast((entry) => entry.state === "claimed")?.data;
+}
+
+export function latestStoppedResponsibilityScope(events, turn) {
+  return (Array.isArray(events) ? events : []).findLast((event) => (
+    event?.type === "odai/responsibility-scope-stopped"
+      && event.data?.turn === turn
+      && typeof event.data?.scopeId === "string"
+  ))?.data;
+}
+
+export function pendingResponsibilityInterruption(events) {
+  const settled = new Set();
+  for (let index = (Array.isArray(events) ? events.length : 0) - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    const scopeId = event?.data?.scopeId;
+    if (typeof scopeId !== "string") continue;
+    if (["odai/responsibility-interruption-consumed", "odai/responsibility-interruption-cleared"].includes(event.type)) {
+      settled.add(scopeId);
+      continue;
+    }
+    if (event.type === "odai/responsibility-interrupted") {
+      return event.data?.reason === "max-tokens" && !settled.has(scopeId)
+        ? event.data
+        : undefined;
+    }
+  }
+  return undefined;
+}
+
+export function pendingResponsibilityScopeRestoration(events) {
+  let candidate;
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type === "odai/responsibility-scope-stopped"
+      && event.data?.baseRoute
+      && event.data?.temporaryRoute) {
+      candidate = event.data;
+      continue;
+    }
+    if (candidate
+      && event?.type === "odai/responsibility-scope-restored"
+      && event.data?.scopeId === candidate.scopeId
+      && event.data?.status === "applied") candidate = undefined;
+  }
+  return candidate;
+}

package/preset/odai/runtime/role-overlays.mjs

@@ -1,27 +1,27 @@
-const DSH_ROLE_OVERLAYS = Object.freeze({
-  researcher: `## DSH researcher execution boundary
-
-This responsibility runs as one read-only child before the primary routing decision. Use only read, glob, grep, and other non-mutating source tools; do not run shell commands, edit, plan, recommend, approve, or delegate. Return JSON only, with no fence and no fields beyond this exact shape: {"schemaVersion":1,"question":"...","facts":[{"claim":"...","excerpt":"exact complete cited line","source":{"path":"repository/relative/path","line":1},"authority":"source role and freshness boundary"}],"conflicts":[],"unknowns":[],"stop":"..."}. Return the smallest useful 2-6 facts from at least two distinct files. DSH validates every cited file, line, and excerpt inside the project root before hashing and exposing this packet to the controller or planner.`,
-  planner: `## DSH planner execution boundary
-
-In auto mode this responsibility runs by replacing the current controller request route, not by starting a child. Retain the current conversation and project context, use only read-only evidence, and do not implement or edit. If the result is mode: planned, execute: executor, and separation has a concrete observable benefit, use odai_route_card to freeze exactly one structured card with non-empty evidence, scope, acceptance conditions, and stop condition. When the original current task already authorizes implementation, immediately submit one executor gap through odai_responsibility_gap so the same task continues without another user prompt. For plan-only work, a new task, expanded scope, or missing user-owned authorization, stop for the minimal user decision instead. Otherwise do not create a route card.`,
-  executor: `## DSH executor execution boundary
-
-In auto mode this responsibility is reachable when an active frozen route card proves observable separation benefit and either the original current task already authorizes implementation or the user explicitly continues it. It runs in the current controller turn because DSH routed children are read-only. Follow the claimed card exactly; do not reinterpret the request, broaden scope, or claim final acceptance. The card is consumed only after the effective executor request route is verified; route failure leaves it retryable.`,
-  reviewer: `## DSH reviewer execution boundary
-
-Start an independent child only from a bounded, hash-addressed packet that contains verified tool evidence. The child's effective request header must match its configured route before its output is accepted. Without such a packet, auto mode may replace the current request route for a read-only same-turn check, but it must state that the result is not independent acceptance and must not edit, fix, or approve release.`,
-  frontend: `## DSH frontend execution boundary
-
-This responsibility runs in the current controller turn so it retains the active conversation, workspace, dev-server, and browser context. It is not an independent child. DSH may use a user-persisted frontend provider/model/reasoning route and, only when that mapping explicitly includes maxTokens, apply that responsibility ceiling instead of the global controller ceiling for this routed turn. The runtime compares the effective DSH request header with that mapping and records an applied, mismatch, or unverified receipt; configuration and self-report are not routing evidence.`,
-});
-
-export function dshRoleContract(role, canonicalContract, referenceContracts = {}) {
-  const canonical = typeof canonicalContract === "string" ? canonicalContract.trim() : "";
-  const overlay = DSH_ROLE_OVERLAYS[role];
-  if (!canonical) throw new Error(`canonical ${role} responsibility contract is unavailable`);
-  const craft = role === "frontend" && typeof referenceContracts.craft === "string"
-    ? `## Canonical craft reference\n\n${referenceContracts.craft.trim()}`
-    : "";
-  return [canonical, craft, overlay].filter(Boolean).join("\n\n");
-}
+const DSH_ROLE_OVERLAYS = Object.freeze({
+  researcher: `## DSH researcher execution boundary
+
+This responsibility runs as one read-only child before the primary routing decision. Use only read, glob, grep, and other non-mutating source tools; do not run shell commands, edit, plan, recommend, approve, or delegate. Return JSON only, with no fence and no fields beyond this exact shape: {"schemaVersion":1,"question":"...","facts":[{"claim":"...","excerpt":"exact complete cited line","source":{"path":"repository/relative/path","line":1},"authority":"source role and freshness boundary"}],"conflicts":[],"unknowns":[],"stop":"..."}. Return the smallest useful 2-6 facts from at least two distinct files. DSH validates every cited file, line, and excerpt inside the project root before hashing and exposing this packet to the controller or planner.`,
+  planner: `## DSH planner execution boundary
+
+In auto mode this responsibility runs by replacing the controller route only inside one explicit responsibility scope, not by starting a child. The scope may continue through read-only tool calls, but ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. When the user-persisted planner mapping explicitly includes maxTokens, that responsibility ceiling overrides the controller ceiling only inside this scope. Retain the current conversation and project context, use only read-only evidence, and do not implement or edit. If the result is mode: planned, execute: executor, and separation has a concrete observable benefit, use odai_route_card to freeze exactly one structured card with non-empty evidence, scope, acceptance conditions, and stop condition. When the original current task already authorizes implementation, immediately submit one executor gap through odai_responsibility_gap so the same task continues without another user prompt. For plan-only work, a new task, expanded scope, or missing user-owned authorization, stop for the minimal user decision instead. Otherwise do not create a route card.`,
+  executor: `## DSH executor execution boundary
+
+In auto mode this responsibility is reachable when an active frozen route card proves observable separation benefit and either the original current task already authorizes implementation or the user explicitly continues it. It runs in one bounded controller responsibility scope because DSH routed children are read-only. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, card release, or turn boundary. When the user-persisted executor mapping explicitly includes maxTokens, that responsibility ceiling overrides the controller ceiling only inside this scope. Follow the claimed card exactly; do not reinterpret the request, broaden scope, or claim final acceptance. The card is consumed after the effective executor request route is verified; that route receipt admits one executor attempt but does not keep the responsibility scope alive by itself.`,
+  reviewer: `## DSH reviewer execution boundary
+
+Start an independent child only from a bounded, hash-addressed packet that contains verified tool evidence. The child's effective request header must match its configured route before its output is accepted. Without such a packet, auto mode keeps the current controller route and may perform only a controller-local read-only check while it gathers project-available acceptance evidence. That local check is not independent acceptance, must not claim reviewer approval, and must not stop the authorized task solely to ask the user for artifacts the project can produce.`,
+  frontend: `## DSH frontend execution boundary
+
+This responsibility runs in one bounded controller responsibility scope so it retains the active conversation, workspace, dev-server, and browser context. It is not an independent child. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. DSH may use a user-persisted frontend provider/model/reasoning route and, only when that mapping explicitly includes maxTokens, apply that responsibility ceiling inside this scope. The runtime compares the effective DSH request header with that mapping and records an applied, mismatch, or unverified receipt; configuration and self-report are not routing evidence.`,
+});
+
+export function dshRoleContract(role, canonicalContract, referenceContracts = {}) {
+  const canonical = typeof canonicalContract === "string" ? canonicalContract.trim() : "";
+  const overlay = DSH_ROLE_OVERLAYS[role];
+  if (!canonical) throw new Error(`canonical ${role} responsibility contract is unavailable`);
+  const craft = role === "frontend" && typeof referenceContracts.craft === "string"
+    ? `## Canonical craft reference\n\n${referenceContracts.craft.trim()}`
+    : "";
+  return [canonical, craft, overlay].filter(Boolean).join("\n\n");
+}