codexteer 0.14.1 → 0.15.1

package/src/cli.mjs

@@ -11,6 +11,9 @@ import { createCheckpoint, listCheckpoints, getCheckpoint, checkpointSummary, ve
 import { acquireResource, resourceStatus, renewResource, releaseResource, listResources, runWithResource } from "./resource.mjs";
 import { playSendSound } from "./sound.mjs";
 import { prepareSupervisorPrompt, superviseAgent } from "./supervise.mjs";
+import { supervisorId, registerSupervisor, getSupervisor, assertSupervisor, controlSupervisor, supervisorStatus, listSupervisors } from "./supervision.mjs";
+import { createFinding, findingStatus, listFindings, resolveFinding, dismissFinding, reopenFinding, evaluateFinding, findingStats } from "./findings.mjs";
+import { connectionMode, observationConnection, desktopReadOnly } from "./connection.mjs";
 
 const DEFAULT_SEND_BACKEND = "app-server";
 
@@ -26,6 +29,8 @@ function fail(error, json) {
     operation: error.operation, capability: error.capability,
     sent: error.sent, thread_id: error.thread_id, rpc_code: error.rpc_code ?? error.rpcCode,
     message_id: error.message_id, client_message_id: error.client_message_id, journal_update_required: error.journal_update_required,
+    existing_message_id: error.existing_message_id,
+    supervision_update_required: error.supervision_update_required,
   } }));
   else console.error(`codexteer: ${message}`);
   process.exitCode = 1;
@@ -76,11 +81,33 @@ function printThreads(threads) {
   }
 }
 
+function printSupervisor(data) {
+  if (Array.isArray(data)) {
+    if (!data.length) console.log("No supervisor sessions registered.");
+    for (const entry of data) console.log(`${entry.thread_id}  ${entry.state}  ${entry.owner}  ${entry.connection}  observed:${entry.observation?.last_observed_at ?? "none"}`);
+    return;
+  }
+  console.log(`${data.thread_id}  ${data.state}${data.owner ? `  ${data.owner}  ${data.connection}` : ""}`);
+  if (data.session_id) console.log(`session: ${data.session_id}`);
+  if (Object.hasOwn(data, "observation")) console.log(`observation: ${data.observation?.connection ?? "none"}  last:${data.observation?.last_observed_at ?? "none"}  age_ms:${data.observation_age_ms ?? "unknown"}`);
+  if (Object.hasOwn(data, "launcher_alive")) console.log(`launcher: ${data.launcher_alive === null ? "unverified (copied prompt)" : data.launcher_alive ? "alive" : "exited"}`);
+  if (data.last_delivery) console.log(`delivery: ${data.last_delivery.status}  message:${data.last_delivery.message_id ?? "none"}`);
+  if (data.last_error) console.log(`last error: ${data.last_error.code}`);
+  if (data.unresolved_findings) {
+    console.log(`unresolved findings: ${data.unresolved_findings.total}`);
+    for (const finding of data.unresolved_findings.findings) console.log(`  ${finding.id}  ${finding.status}  ${finding.title}`);
+  }
+}
+
 export async function main(argv) {
   const args = [...argv];
   let json = takeFlag(args, "--json");
 
   try {
+    const sessionOption = takeOption(args, "--supervisor", undefined);
+    const supervisor = sessionOption === undefined ? undefined : supervisorId(sessionOption);
+    const connection = connectionMode(takeOption(args, "--connection", "shared"));
+    const connectionDependencies = observationConnection(connection);
     const requiredNode = takeOption(args, "--require-node-version", undefined);
     if (requiredNode !== undefined) {
       if (!/^v\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(requiredNode)) throw new Error("--require-node-version requires a Node version such as v25.1.0.");
@@ -103,22 +130,73 @@ export async function main(argv) {
     }
 
     let command = args.shift();
+    // An explicit observation endpoint can never silently route a mutation to
+    // the shared wrapper or UI. Local records/help remain available.
+    if (connection === "desktop" && !["supervise", "findings", "history", "instructions", "checkpoint", "resource", "read", "status", "watch", "doctor", "threads", "thread"].includes(command)) throw desktopReadOnly();
+    if (command === "supervise" && ["register", "status", "list", "pause", "resume", "stop"].includes(args[0])) {
+      const action = args.shift(), owner = action === "register" ? takeOption(args, "--owner", "external") : undefined;
+      if (args.length !== (action === "list" ? 0 : 1)) throw new Error(`Expected: supervise ${action}${action === "list" ? "" : " <THREAD>"}.`);
+      let data;
+      if (action === "register") {
+        if (!supervisor) throw new Error("supervise register requires the --supervisor ID from a generated prompt.");
+        data = await registerSupervisor(args[0], supervisor, { owner, connection });
+      } else {
+        if (supervisor && action !== "status") throw Object.assign(new Error("Supervisors cannot change their own control state. Run this control command from the user's terminal without --supervisor."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
+        if (supervisor) {
+          const record = await getSupervisor(args[0]);
+          if (record?.session_id !== supervisor) throw Object.assign(new Error("This supervisor belongs to a different session or task."), { code: "SUPERVISOR_MISMATCH" });
+        }
+        data = action === "list" ? await listSupervisors() : action === "status" ? await supervisorStatus(args[0]) : await controlSupervisor(args[0], action);
+        if (action === "status") {
+          const pending = await listFindings(args[0], { limit: 20 });
+          data.unresolved_findings = { total: pending.total, has_more: pending.has_more,
+            findings: pending.findings.map(finding => ({ id: finding.id, title: finding.title, status: finding.status, revision: finding.revision })) };
+        }
+      }
+      success(`supervise.${action}`, data, json);
+      if (!json) printSupervisor(data);
+      return;
+    }
+    if (command === "findings") {
+      const action = args.shift();
+      const flags = names => Object.fromEntries(names.map(([field, option]) => [field, takeOption(args, option, undefined)]));
+      let options = {}, data;
+      if (action === "create") options = { ...flags([["key", "--key"], ["title", "--title"], ["condition", "--condition"], ["basedOn", "--based-on"]]), evidence: takeOptions(args, "--evidence") };
+      else if (action === "resolve") options = flags([["checkpoint", "--checkpoint"], ["note", "--note"]]);
+      else if (action === "dismiss") options = flags([["reason", "--reason"]]);
+      else if (action === "reopen") {
+        options = flags([["reason", "--reason"], ["condition", "--condition"], ["basedOn", "--based-on"]]);
+        const evidence = takeOptions(args, "--evidence"); if (evidence.length) options.evidence = evidence;
+      } else if (action === "evaluate") options = flags([["rating", "--rating"], ["reason", "--reason"]]);
+      else if (action === "list") options = { all: takeFlag(args, "--all"), limit: Number(takeOption(args, "--limit", "50")) };
+      const handlers = { create: createFinding, show: findingStatus, list: listFindings, resolve: resolveFinding, dismiss: dismissFinding, reopen: reopenFinding, evaluate: evaluateFinding, stats: findingStats };
+      const single = ["create", "list", "stats"].includes(action);
+      if (!Object.hasOwn(handlers, action) || args.length !== (single ? 1 : 2) || args.some(arg => arg.startsWith("--"))) throw new Error("See codexteer help findings.");
+      if (supervisor) await assertSupervisor(args[0], supervisor, { connection });
+      data = single ? await handlers[action](args[0], options) : await handlers[action](args[0], args[1], options);
+      success(`findings.${action}`, data, json);
+      if (!json) console.log(JSON.stringify(data, null, 2));
+      return;
+    }
     if (command === "supervise" && args[0] === "prompt") {
       args.shift();
-      if (args.length !== 1) throw new Error("Expected: supervise prompt <THREAD>. See codexteer help supervise prompt.");
-      const data = await prepareSupervisorPrompt(args[0]);
+      const agent = takeOption(args, "--agent", "claude");
+      if (args.length < 1 || args.length > 2 || args.some(arg => arg.startsWith("--"))) throw new Error("Expected: supervise prompt <THREAD> [MESSAGE]. See codexteer help supervise prompt.");
+      if (supervisor) throw new Error("A supervisor cannot generate a replacement session.");
+      const data = await prepareSupervisorPrompt(args[0], args[1], { agent, connection });
       success("supervise.prompt", data, json);
       if (!json) console.log(data.prompt);
       return;
     }
     if (command === "supervise") {
+      if (supervisor) throw new Error("A supervisor cannot start a replacement session.");
       if (json) throw new Error("supervise inherits agent output and does not support --json. Use help supervise --json or supervise prompt <THREAD> --json.");
       const separator = args.indexOf("--");
       const ownArgs = separator < 0 ? args : args.slice(0, separator);
       const agentArgs = separator < 0 ? [] : args.slice(separator + 1);
-      const agent = takeOption(ownArgs, "--agent", undefined);
-      if (ownArgs.length !== 1 || !agent) throw new Error("Expected: supervise <THREAD> --agent claude [-- <AGENT-ARGS...>].");
-      process.exitCode = await superviseAgent(ownArgs[0], { agent, agentArgs });
+      const agent = takeOption(ownArgs, "--agent", "claude");
+      if (ownArgs.length < 1 || ownArgs.length > 2 || ownArgs.some(arg => arg.startsWith("--"))) throw new Error("Expected: supervise <THREAD> [MESSAGE] [--agent claude|codex] [-- <AGENT-ARGS...>].");
+      process.exitCode = await superviseAgent(ownArgs[0], { agent, agentArgs, policy: ownArgs[1], connection });
       return;
     }
     if (command === "resource") {
@@ -148,6 +226,7 @@ export async function main(argv) {
     }
     if (command === "checkpoint") {
       const action = args.shift(), includeOutput = takeFlag(args, "--include-output");
+      if (supervisor) await assertSupervisor(args[0], supervisor, { connection });
       let data;
       if (action === "capture") {
         const paths = takeOptions(args, "--path"), excludes = takeOptions(args, "--exclude");
@@ -180,16 +259,18 @@ export async function main(argv) {
       if (action === "list") {
         const all = takeFlag(args, "--all");
         if (args.length !== 1) throw new Error("Expected: instructions list <THREAD> [--all].");
+        if (supervisor) await assertSupervisor(args[0], supervisor, { connection });
         const data = await listInstructions(args[0], { all });
         success("instructions.list", data, json);
         if (!json) { for (const entry of data.instructions) console.log(`${entry.id}  ${entry.instruction_status}  ${entry.metadata?.source ?? "unspecified"}\n${entry.body}`); if (data.pending_changes.length) console.log(`配送未確認: ${data.pending_changes.map(e => e.id).join(", ")}`); }
         return;
       }
       if (action !== "retract") throw new Error("See codexteer help instructions.");
+      if (connection === "desktop") throw desktopReadOnly();
       const reason = takeOption(args, "--reason", undefined), source = takeOption(args, "--source", undefined), basedOn = takeOption(args, "--based-on", undefined);
       const dryRun = takeFlag(args, "--dry-run"), newTurn = takeFlag(args, "--new-turn");
       if (args.length !== 2 || !reason?.trim()) throw new Error("Expected: instructions retract <THREAD> <MESSAGE-ID> --reason TEXT.");
-      const data = await sendTrackedMessage(args[0], reason, { retracts: args[1], source, basedOn, dryRun, newTurn });
+      const data = await sendTrackedMessage(args[0], reason, { retracts: args[1], source, basedOn, dryRun, newTurn, supervisor, connection });
       success("instructions.retract", data, json);
       if (!json) console.log(dryRun ? "撤回の送信プレビューです。" : `撤回を受け付けました。message_id: ${data.message_id}`);
       return;
@@ -201,7 +282,8 @@ export async function main(argv) {
       const report = action === "mark" ? { status: takeOption(args, "--status", undefined), note: takeOption(args, "--note", undefined), evidence: takeOptions(args, "--evidence"), by: takeOption(args, "--by", "local") } : {};
       const [threadId, id] = args;
       if (!threadId || args.length > 2 || !["list", "show", "check", "mark"].includes(action) || (["show", "mark"].includes(action) && !id) || (action === "list" && id)) throw new Error("See codexteer help history.");
-      const data = action === "list" ? await listMessages(threadId, { includeText, pending }) : action === "show" ? messageSummary(await getMessage(threadId, id), includeText) : action === "check" ? await reconcileMessages(threadId, id, { includeText }) : await markMessage(threadId, id, report);
+      if (supervisor) await assertSupervisor(threadId, supervisor, { connection });
+      const data = action === "list" ? await listMessages(threadId, { includeText, pending }) : action === "show" ? messageSummary(await getMessage(threadId, id), includeText) : action === "check" ? await reconcileMessages(threadId, id, { includeText }, connectionDependencies) : await markMessage(threadId, id, report);
       success(`history.${action}`, data, json);
       if (!json) for (const entry of Array.isArray(data) ? data : [data]) console.log(`${entry.id}  ${entry.delivery_status}  history:${entry.verification?.status ?? "unchecked"}  response:${entry.response.status}${entry.body ? "\n" + entry.body : ""}`);
       return;
@@ -215,6 +297,7 @@ export async function main(argv) {
         maxChars: Number(takeOption(args, "--max-chars", "2000")),
         includeOutput: takeFlag(args, "--include-output"),
       };
+      options.supervisor = supervisor; options.connection = connection;
       const stream = command === "watch" && takeFlag(args, "--stream");
       if (stream) json = true;
       if (command === "watch") {
@@ -223,8 +306,9 @@ export async function main(argv) {
         Object.assign(options, { watch: true, until: until ?? "change", timeoutMs: Number(timeout ?? "30000"), pollMs: Number(takeOption(args, "--poll-ms", "1000")) });
       }
       if (args.length !== 1) throw new Error(`Expected: ${command} <THREAD>. See codexteer help ${command}.`);
-      if (stream) { await monitorCommand(args[0], options); return; }
-      const data = await observeThread(args[0], options);
+      if (stream) { await monitorCommand(args[0], options, connectionDependencies); return; }
+      const data = await observeThread(args[0], options, connectionDependencies);
+      data.connection_mode = connection;
       if (command === "status") delete data.events;
       success(command, data, json);
       if (!json) printObservation(data, command === "status");
@@ -232,11 +316,18 @@ export async function main(argv) {
     }
     if (command === "doctor") {
       const backend = backendOption(args, "app-server");
+      if (connection === "desktop" && backend === "ui") throw desktopReadOnly();
       const target = takeOption(args, "--thread", undefined);
       if (target !== undefined && backend !== "app-server") throw new Error("doctor --thread requires --backend app-server.");
       const threadId = target === undefined ? undefined : normalizeThreadId(target);
+      if (supervisor && threadId) {
+        const record = await getSupervisor(threadId);
+        if (record && record.session_id !== supervisor && record.state !== "stopped") throw Object.assign(new Error("Another supervisor is registered for this task."), { code: "SUPERVISOR_CONFLICT" });
+        if (record?.session_id === supervisor) await assertSupervisor(threadId, supervisor, { connection });
+      }
       if (args.length) throw new Error(`Unexpected argument: ${args[0]}`);
-      const report = backend === "ui" ? desktopDoctor() : await appServerDoctor({ threadId });
+      const report = backend === "ui" ? desktopDoctor() : await appServerDoctor({ threadId, ...connectionDependencies });
+      if (report.connection) Object.assign(report.connection, { mode: connection, observation_only: connection === "desktop" });
       report.default_send_backend = DEFAULT_SEND_BACKEND;
       report.rollout_status = "enabled";
       success("doctor", report, json);
@@ -322,13 +413,14 @@ export async function main(argv) {
 
     const dryRun = takeFlag(args, "--dry-run");
     const backend = backendOption(args, DEFAULT_SEND_BACKEND);
+    if (supervisor && backend !== "app-server") throw new Error("Managed supervision requires the app-server backend.");
     const explicitSound = takeFlag(args, "--sound");
     const noSound = takeFlag(args, "--no-sound");
     if (explicitSound && noSound) throw new Error("--sound and --no-sound cannot be combined.");
     if (explicitSound && backend !== "app-server") throw new Error("--sound requires --backend app-server so receipt can be confirmed.");
     const newTurn = takeFlag(args, "--new-turn");
-    const directive = { source: takeOption(args, "--source", undefined), kind: takeOption(args, "--kind", undefined), evidence: takeOptions(args, "--evidence"), basedOn: takeOption(args, "--based-on", undefined), supersedes: takeOption(args, "--supersedes", undefined), expiresAt: takeOption(args, "--expires-at", undefined), checkpoint: takeOption(args, "--checkpoint", undefined) };
-    if (backend === "ui" && (directive.source || directive.kind || directive.evidence.length || directive.basedOn || directive.supersedes || directive.expiresAt || directive.checkpoint)) throw new Error("Directive metadata requires --backend app-server.");
+    const directive = { source: takeOption(args, "--source", undefined), kind: takeOption(args, "--kind", undefined), evidence: takeOptions(args, "--evidence"), basedOn: takeOption(args, "--based-on", undefined), supersedes: takeOption(args, "--supersedes", undefined), expiresAt: takeOption(args, "--expires-at", undefined), checkpoint: takeOption(args, "--checkpoint", undefined), finding: takeOption(args, "--finding", undefined) };
+    if (backend === "ui" && (directive.source || directive.kind || directive.evidence.length || directive.basedOn || directive.supersedes || directive.expiresAt || directive.checkpoint || directive.finding)) throw new Error("Directive metadata requires --backend app-server.");
     const keepFocus = takeFlag(args, "--keep-focus");
     const waitInput = takeOption(args, "--wait-ms", undefined);
     if (backend !== "ui" && (keepFocus || waitInput != null)) throw new Error("--keep-focus and --wait-ms require --backend ui.");
@@ -339,7 +431,7 @@ export async function main(argv) {
     if (message.trim() === "") throw new Error("send requires a non-empty message.");
     const threadId = normalizeThreadId(threadInput);
     const data = backend === "app-server"
-      ? await sendTrackedMessage(threadId, message, { dryRun, newTurn, ...directive })
+      ? await sendTrackedMessage(threadId, message, { dryRun, newTurn, ...directive, supervisor, connection })
       : sendDesktopMessage(threadId, message, { dryRun, waitMs, newTurn, keepFocus });
     data.sound = noSound ? { played: false, reason: "disabled" } : playSendSound(data);
     success("send", data, json);

package/src/compatibility.mjs

@@ -63,6 +63,9 @@ export function runtimeCompatibility(state, { verifiedMethods = [], unsupportedM
       }
     }
     const probes = name === "thread_read" ? ["thread/read"] : name === "history_pagination" ? ["thread/turns/list", "thread/items/list"] : [];
+    if (state?.native_observation_only && ["turn_steer", "turn_start", "desktop_subscribe"].includes(name)) {
+      status = "unsupported"; source = "observation-only"; versions = [];
+    }
     if (source === "probe" && probes.length) {
       // One missing required API disproves support even if another probe succeeded.
       if (probes.some(method => unsupportedMethods.includes(method))) {

package/src/connection.mjs

@@ -0,0 +1,107 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { codexHome } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+
+const failure = (message, code) => Object.assign(new Error(message), { code });
+const reads = new Set(["thread/loaded/list", "thread/read", "thread/turns/list", "thread/items/list"]);
+export function connectionMode(value = "shared") {
+  if (!["shared", "desktop"].includes(value)) throw new Error("--connection must be shared or desktop.");
+  return value;
+}
+export function desktopReadOnly() {
+  return failure("The desktop connection supports observation only. Use the existing shared connection for sends; connections are never switched automatically.", "DESKTOP_READ_ONLY");
+}
+
+async function identity(home) {
+  const directory = path.join(home, "app-server-control"), socket = path.join(directory, "app-server-control.sock");
+  const fingerprint = [];
+  for (const [file, type] of [[home, "home"], [directory, "directory"], [socket, "socket"]]) {
+    const info = await lstat(file);
+    if (info.uid !== process.getuid() || info.isSymbolicLink() || (info.mode & (type === "home" ? 0o022 : 0o077)) !== 0
+      || (type === "socket" ? !info.isSocket() : !info.isDirectory())) {
+      throw failure("Desktop control endpoint has unsafe ownership, permissions, or file type.", "DESKTOP_CONNECTION_UNSAFE");
+    }
+    // Home directory timestamps change for unrelated profile activity.
+    fingerprint.push([info.dev, info.ino, type === "socket" ? info.ctimeMs : null]);
+  }
+  return { home, directory, socket, fingerprint: JSON.stringify(fingerprint) };
+}
+
+export async function discoverDesktopRuntime(home = codexHome()) {
+  try {
+    const paths = await identity(await realpath(home));
+    return { paths, state: { codex_home: paths.home, native_observation_only: true } };
+  } catch (error) {
+    if (error.code === "ENOENT") throw failure("No existing Desktop control socket was found in this CODEX_HOME. Direct observation requires Desktop to be using its shared local daemon. This command does not start or restart it.", "DESKTOP_CONNECTION_UNAVAILABLE");
+    if (["EPERM", "EACCES"].includes(error.code)) throw failure("Cannot inspect the Desktop control endpoint.", "PERMISSION_DENIED");
+    throw error;
+  }
+}
+
+async function stillCurrent(paths) {
+  let current;
+  try { current = await identity(paths.home); }
+  catch (error) {
+    if (error.code === "ENOENT") throw failure("The Desktop endpoint disappeared. Recheck the selected connection before observing again.", "DESKTOP_CONNECTION_CHANGED");
+    throw error;
+  }
+  if (current.fingerprint !== paths.fingerprint) throw failure("The Desktop endpoint changed. Recheck the selected connection before observing again.", "DESKTOP_CONNECTION_CHANGED");
+}
+
+async function requireLoaded(client, threadId) {
+  const seen = new Set(); let cursor;
+  for (let page = 0; page < 100; page++) {
+    const result = await client.request("thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+    if (!Array.isArray(result?.data) || !result.data.every(id => typeof id === "string")
+      || (result.nextCursor != null && (typeof result.nextCursor !== "string" || !result.nextCursor || seen.has(result.nextCursor)))) {
+      throw failure("Invalid loaded-task list from Desktop.", "PROTOCOL_ERROR");
+    }
+    if (result.data.includes(threadId)) return;
+    cursor = result.nextCursor;
+    if (!cursor) throw failure("The target is not loaded in this Desktop endpoint. Select the matching profile and loaded task; codexteer will not resume it implicitly.", "DESKTOP_THREAD_NOT_LOADED");
+    seen.add(cursor);
+  }
+  throw failure("The loaded-task list exceeded the observation limit.", "PROTOCOL_ERROR");
+}
+
+export async function connectDesktop(paths, options, connect = RpcClient.connect) {
+  await stillCurrent(paths);
+  const client = await connect(paths.socket, options);
+  try { await stillCurrent(paths); } catch (error) { client.close(); throw error; }
+  return {
+    close: () => client.close(),
+    async request(method, params = {}, requestOptions = {}) {
+      if (!reads.has(method) || requestOptions.mutation) throw desktopReadOnly();
+      await stillCurrent(paths);
+      if (method !== "thread/loaded/list") {
+        if (typeof params.threadId !== "string" || !params.threadId) throw failure("A target task is required for Desktop observation.", "PROTOCOL_ERROR");
+        await requireLoaded(client, params.threadId);
+        await stillCurrent(paths);
+      }
+      const result = await client.request(method, params, requestOptions);
+      await stillCurrent(paths);
+      return result;
+    },
+  };
+}
+
+// Each operation owns its discovery result. No implicit fallback to another
+// profile, daemon, or wrapper, including after connection failures.
+export function observationConnection(mode) {
+  if (connectionMode(mode) === "shared") return {};
+  let selected;
+  return {
+    async discover(home) {
+      const discovered = await discoverDesktopRuntime(home);
+      if (selected && (selected.paths.home !== discovered.paths.home || selected.paths.fingerprint !== discovered.paths.fingerprint)) {
+        throw failure("The Desktop endpoint changed during observation. Check it before explicitly starting another watch.", "DESKTOP_CONNECTION_CHANGED");
+      }
+      selected = discovered; return selected;
+    },
+    async connect(socket, options) {
+      if (!selected || selected.paths.socket !== socket) throw failure("Desktop discovery is required before connection.", "DESKTOP_CONNECTION_UNAVAILABLE");
+      return connectDesktop(selected.paths, options);
+    },
+  };
+}

package/src/directive.mjs

@@ -2,12 +2,14 @@ import { collectEvidence, verifyEvidence } from "./evidence.mjs";
 import { decodeCursor, threadSnapshot, fetchThread } from "./observe.mjs";
 import { getCheckpoint, verifyCheckpoint } from "./checkpoint.mjs";
 import { verifyPagedFreshness } from "./paged-read.mjs";
+import { assertFindingSend, getFinding } from "./findings.mjs";
 
 export const kindLabels = { decision: "ユーザー決定の伝達", review: "レビュー", hypothesis: "仮説（未確定）", suggestion: "任意提案" };
 
 export async function prepareDirective(threadId, body, options, id, storage = {}) {
-  const { source, kind, evidence = [], basedOn, supersedes, retracts, expiresAt, checkpoint } = options;
-  if (!source && !kind && !evidence.length && !basedOn && !supersedes && !retracts && !expiresAt && !checkpoint) return { wireText: body, metadata: null };
+  const { source, kind, evidence = [], basedOn, supersedes, retracts, expiresAt, checkpoint, finding, supervisor } = options;
+  if (!source && !kind && !evidence.length && !basedOn && !supersedes && !retracts && !expiresAt && !checkpoint && !finding && !supervisor) return { wireText: body, metadata: null };
+  const concern = finding ? await assertFindingSend(threadId, finding, storage) : null;
   if (checkpoint) await getCheckpoint(threadId, checkpoint, storage);
   if (supersedes && retracts) throw new Error("Use either supersedes or retracts, not both.");
   if (expiresAt && (!/(Z|[+-]\d{2}:\d{2})$/.test(expiresAt) || !Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= Date.now())) throw new Error("--expires-at must be a future ISO timestamp with timezone.");
@@ -15,7 +17,8 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
   if (source != null && (!source.trim() || source.length > 80 || /[\r\n\x00-\x1f]/.test(source))) throw new Error("--source must be a non-empty single line (up to 80 characters).");
   const observed = basedOn ? decodeCursor(basedOn, threadId) : null;
   const refs = await collectEvidence(evidence);
-  const metadata = { source: source ?? "external", kind: kind ?? "review", evidence: refs, based_on: basedOn ?? null, supersedes: supersedes ?? null, retracts: retracts ?? null, expires_at: expiresAt ?? null, checkpoint_id: checkpoint ?? null };
+  const metadata = { source: source ?? "external", kind: kind ?? "review", evidence: refs, based_on: basedOn ?? null, supersedes: supersedes ?? null, retracts: retracts ?? null, expires_at: expiresAt ?? null, checkpoint_id: checkpoint ?? null,
+    ...(concern ? { finding_id: concern.id, finding_revision: concern.revision } : {}), ...(supervisor ? { supervisor_id: supervisor } : {}) };
   const lines = [`[codexteer ${id}]`, `送信者: ${metadata.source}`, `種類: ${kindLabels[metadata.kind]}`];
   for (const ref of refs) lines.push(`根拠: ${JSON.stringify(ref.ref)}${ref.sha256 ? ` (sha256:${ref.sha256})` : " (参照URL)"}`);
   if (observed) lines.push(`観測対象ターン: ${observed.active_turn_id ?? "停止中"}`);
@@ -23,6 +26,7 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
   if (retracts) lines.push(`撤回する指示: ${retracts}。以後の方針から除外してください。`);
   if (expiresAt) lines.push(`有効期限: ${expiresAt}`);
   if (checkpoint) lines.push(`検証チェックポイント: ${checkpoint}`);
+  if (concern) lines.push(`指摘: ${concern.id} (revision ${concern.revision})`, `解決条件: ${JSON.stringify(concern.condition)}`);
   return { metadata, wireText: lines.join("\n") + "\n\n" + body, async beforeSend(thread, client) {
     if (expiresAt && Date.parse(expiresAt) <= Date.now()) throw Object.assign(new Error("Directive expired before sending."), { code: "EXPIRED_DIRECTIVE" });
     if (observed) {
@@ -35,5 +39,10 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
     }
     await verifyEvidence(refs);
     if (checkpoint && !(await verifyCheckpoint(threadId, checkpoint, storage)).valid) throw Object.assign(new Error("Checkpoint is no longer valid. Verify the inputs and results before sending."), { code: "STALE_CHECKPOINT" });
+    if (concern) {
+      const current = await getFinding(threadId, concern.id, storage);
+      if (current.revision !== concern.revision || current.disposition !== "open") throw Object.assign(new Error("The finding changed before sending. Reassess it before intervening."), { code: "STALE_FINDING" });
+      await verifyEvidence(concern.evidence);
+    }
   } };
 }

package/src/findings.mjs

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
+import { collectEvidence } from "./evidence.mjs";
+import { decodeCursor, digest } from "./observe.mjs";
+import { verifyCheckpoint } from "./checkpoint.mjs";
+
+const failure = (message, code) => Object.assign(new Error(message), { code });
+const ratings = ["useful", "unnecessary", "incorrect", "unrated"];
+const text = (value, label, max = 8000) => {
+  if (typeof value !== "string" || !value.trim() || value.length > max || value.includes("\0")) throw failure(`${label} requires non-empty text (up to ${max} characters).`, "FINDING_INVALID");
+  return value;
+};
+// A cursor can advance because our own intervention appeared as a userMessage.
+// It is observation context, never sufficient evidence for another intervention.
+const contextHash = record => digest({ condition: record.condition, evidence: record.evidence });
+
+export async function getFinding(threadInput, id, storage = {}) {
+  const threadId = normalizeThreadId(threadInput), record = await readRecord("findings", id, storage);
+  if (!record || record.schema !== 1 || record.id !== id || record.thread_id !== threadId) throw failure("Finding not found for this task.", "FINDING_NOT_FOUND");
+  if (!Number.isSafeInteger(record.revision) || record.revision < 1 || !["open", "resolved", "dismissed"].includes(record.disposition)
+    || !Array.isArray(record.evidence) || typeof record.condition !== "string" || !ratings.includes(record.evaluation?.rating)) throw failure("Invalid finding record.", "FINDING_INVALID");
+  return record;
+}
+
+export async function findingMessages(record, storage = {}) {
+  return (await listRecords("messages", storage)).filter(message => message?.schema === 1 && message.thread_id === record.thread_id
+    && message.metadata?.finding_id === record.id && message.metadata?.finding_revision === record.revision)
+    .sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+
+export async function createFinding(threadInput, { key, title, condition, evidence = [], basedOn, ...storage }) {
+  const threadId = normalizeThreadId(threadInput);
+  if (typeof key !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,150}$/.test(key)) throw failure("--key requires a stable short identifier for this concern.", "FINDING_INVALID");
+  text(title, "--title", 240); text(condition, "--condition");
+  const refs = await collectEvidence(evidence), observed = basedOn ? decodeCursor(basedOn, threadId) : null;
+  return withStoreLock(`message-${threadId}`, async () => {
+    const existing = (await listRecords("findings", storage)).find(record => record?.thread_id === threadId && record.key === key);
+    if (existing) return { ...await findingStatus(threadId, existing.id, storage), reused: true };
+    const now = new Date().toISOString();
+    const record = { schema: 1, id: randomUUID(), thread_id: threadId, key, title, condition, revision: 1,
+      evidence: refs, based_on: basedOn ?? null, user_revision: observed?.user_revision ?? null, disposition: "open", resolution: null,
+      evaluation: { rating: "unrated" }, revisions: [], created_at: now, updated_at: now };
+    await writeRecord("findings", record.id, record, storage);
+    return { ...record, status: "open", messages: [], verification: null, reused: false };
+  }, storage);
+}
+
+export async function assertFindingSend(threadInput, id, storage = {}) {
+  const record = await getFinding(threadInput, id, storage);
+  if (record.disposition !== "open") throw failure("This finding is closed. Reopen it with new evidence or a changed requirement before sending again.", "FINDING_CLOSED");
+  // The journal is the reservation: even a crash before writing a receipt leaves
+  // an unknown attempt here. Never infer not-sent from a missing response.
+  const previous = (await findingMessages(record, storage)).find(message => message.delivery_status !== "not_sent");
+  if (previous) throw Object.assign(failure("This finding revision already has a pending or accepted intervention. Check its history; do not resend it.", "DUPLICATE_INTERVENTION"), { existing_message_id: previous.id });
+  return record;
+}
+
+export async function findingStatus(threadInput, id, storage = {}) {
+  const record = await getFinding(threadInput, id, storage), entries = await findingMessages(record, storage);
+  const messages = entries.map(entry => ({ id: entry.id, delivery_status: entry.delivery_status, attempt_state: entry.attempt_state,
+    response: entry.response, stored: entry.verification?.status ?? "unchecked" }));
+  const latest = entries.filter(entry => entry.delivery_status !== "not_sent").at(-1);
+  let status = record.disposition, verification = null;
+  if (record.disposition === "open" && latest) status = latest.delivery_status === "unknown" ? "delivery_unknown"
+    : latest.response?.status === "applied" ? "awaiting_verification" : "awaiting_response";
+  if (record.resolution?.checkpoint_id) {
+    try {
+      const current = await verifyCheckpoint(record.thread_id, record.resolution.checkpoint_id, storage);
+      verification = { valid: current.valid === true && current.latest_run?.id === record.resolution.run_id && current.snapshot.digest === record.resolution.input_digest,
+        checkpoint_id: current.id, run_id: current.latest_run?.id ?? null, inputs_current: current.inputs_current,
+        checked_at: new Date().toISOString(), condition_assessment: "explicit_report" };
+    } catch (error) { verification = { valid: false, checkpoint_id: record.resolution.checkpoint_id, error_code: error.code ?? "CHECKPOINT_UNAVAILABLE", condition_assessment: "explicit_report" }; }
+    if (!verification.valid && record.disposition === "resolved") status = "needs_review";
+  }
+  return { ...record, status, messages, verification };
+}
+
+export async function listFindings(threadInput, { all = false, limit = 50, ...storage } = {}) {
+  const threadId = normalizeThreadId(threadInput);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) throw failure("--limit must be between 1 and 1000.", "FINDING_INVALID");
+  const records = (await listRecords("findings", storage)).filter(record => record?.thread_id === threadId).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+  // Recheck closed resolutions too: changed inputs make them unresolved again.
+  const findings = [];
+  for (const record of records) {
+    const current = await findingStatus(threadId, record.id, storage);
+    if (all || !["resolved", "dismissed"].includes(current.status)) findings.push(current);
+  }
+  return { thread_id: threadId, findings: findings.slice(0, limit), total: findings.length, has_more: findings.length > limit };
+}
+
+async function changeFinding(threadInput, id, update, storage) {
+  const threadId = normalizeThreadId(threadInput);
+  return withStoreLock(`message-${threadId}`, async () => {
+    const record = await getFinding(threadId, id, storage);
+    const updated = { ...await update(record), updated_at: new Date().toISOString() };
+    await writeRecord("findings", id, updated, storage);
+    return findingStatus(threadId, id, storage);
+  }, storage);
+}
+
+async function knownDelivery(record, storage) {
+  if ((await findingMessages(record, storage)).some(entry => entry.delivery_status === "unknown")) throw failure("Delivery is unknown. Reconcile the existing message before closing or revising this finding.", "FINDING_DELIVERY_UNKNOWN");
+}
+
+export async function resolveFinding(threadInput, id, { checkpoint, note, ...storage }) {
+  text(note, "--note");
+  if (!checkpoint) throw failure("Resolution requires a --checkpoint and an explicit --note explaining how its result satisfies the condition.", "FINDING_INVALID");
+  return changeFinding(threadInput, id, async record => {
+    await knownDelivery(record, storage);
+    const verified = await verifyCheckpoint(record.thread_id, checkpoint, storage);
+    if (!verified.valid) throw failure("The checkpoint is not currently valid. Verify current inputs and a successful run before resolving.", "STALE_CHECKPOINT");
+    return { ...record, disposition: "resolved", resolution: { checkpoint_id: checkpoint, run_id: verified.latest_run.id,
+      input_digest: verified.snapshot.digest, note, basis: "explicit_report", at: new Date().toISOString() } };
+  }, storage);
+}
+
+export async function dismissFinding(threadInput, id, { reason, ...storage }) {
+  text(reason, "--reason");
+  return changeFinding(threadInput, id, async record => {
+    await knownDelivery(record, storage);
+    return { ...record, disposition: "dismissed", resolution: { reason, basis: "explicit_report", at: new Date().toISOString() } };
+  }, storage);
+}
+
+export async function reopenFinding(threadInput, id, { reason, evidence, basedOn, condition, ...storage }) {
+  const threadId = normalizeThreadId(threadInput);
+  text(reason, "--reason"); if (condition !== undefined) text(condition, "--condition");
+  const refs = evidence === undefined ? undefined : await collectEvidence(evidence);
+  const observed = basedOn === undefined ? undefined : decodeCursor(basedOn, threadId);
+  return changeFinding(threadId, id, async record => {
+    await knownDelivery(record, storage);
+    const updated = { ...record, condition: condition ?? record.condition, evidence: refs ?? record.evidence, based_on: basedOn ?? record.based_on, user_revision: observed?.user_revision ?? record.user_revision };
+    if (contextHash(record) === contextHash(updated)) throw failure("Reopening requires changed evidence or a changed resolution condition. A new reason or cursor alone does not authorize a duplicate intervention; reflect a changed user requirement in the condition.", "FINDING_UNCHANGED");
+    return { ...updated, revision: record.revision + 1, disposition: "open", resolution: null, evaluation: { rating: "unrated" },
+      revisions: [...record.revisions, { revision: record.revision, condition: record.condition, evidence: record.evidence,
+        based_on: record.based_on, user_revision: record.user_revision, resolution: record.resolution, evaluation: record.evaluation, reason, at: new Date().toISOString() }] };
+  }, storage);
+}
+
+export async function evaluateFinding(threadInput, id, { rating, reason, ...storage }) {
+  if (!ratings.includes(rating) || rating === "unrated") throw failure("--rating must be useful, unnecessary or incorrect.", "FINDING_INVALID");
+  text(reason, "--reason");
+  return changeFinding(threadInput, id, async record => ({ ...record, evaluation: { rating, reason, basis: "explicit_report", at: new Date().toISOString() } }), storage);
+}
+
+export async function findingStats(threadInput, storage = {}) {
+  const threadId = normalizeThreadId(threadInput), records = (await listRecords("findings", storage)).filter(record => record?.thread_id === threadId);
+  const counts = Object.fromEntries(ratings.map(rating => [rating, 0]));
+  let sent = 0;
+  for (const entry of records) {
+    const record = await getFinding(threadId, entry.id, storage);
+    counts[record.evaluation.rating]++;
+    if ((await findingMessages(record, storage)).some(message => message.delivery_status !== "not_sent")) sent++;
+  }
+  const evaluated = records.length - counts.unrated;
+  return { thread_id: threadId, scope: "current_finding_revisions_including_unsent_candidates", total: records.length,
+    sent_or_unknown: sent, unsent_candidates: records.length - sent, ratings: counts, evaluated,
+    useful_fraction: evaluated ? counts.useful / evaluated : null };
+}