totemlayer 0.1.21 → 0.1.24

package/bin/installation.mjs

@@ -5,6 +5,11 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensureInstalledRuntime, installRuntimeService } from "./runtime-installation.mjs";
 import { beginDeviceLogin } from "./device-login.mjs";
+import { resumeDeviceLogin } from "./device-login.mjs";
+import { beginBoundLogin } from "./bound-login.mjs";
+import { readAgentProfile } from "./agent-profile.mjs";
+import { readAgentRuntimeStatus } from "./agent-runner.mjs";
+import { setTimeout as sleep } from "node:timers/promises";
 import { detectInstalledProvider, providerArguments } from "./provider-detection.mjs";
 
 export async function activateConnection(profile, env = process.env, options = {}) {
@@ -19,7 +24,7 @@ export async function activateConnection(profile, env = process.env, options = {
   if (!enabled) return { state: "paused", ...service, entry: runtime.cli };
   const { verifyExecutorReady } = await import("./executor-readiness.mjs");
   try {
-    await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
+    if (profile.codexThreadId) await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
   } catch (error) {
     return {
       state: "needs_attention",
@@ -31,42 +36,18 @@ export async function activateConnection(profile, env = process.env, options = {
     };
   }
   const { agentStartMain } = await import("./agent-runner.mjs");
-  const started = await (options.start ?? agentStartMain)(
+  const result = await (options.start ?? agentStartMain)(
     ["--profile", profile.profileName, "--background", "--json"],
     { env, automatic: true, stdout: { write() {} } },
   );
-  if (started !== 0)
-    return {
-      state: "needs_attention",
-      ...service,
-      entry: runtime.cli,
-      code: "WORKER_START_FAILED",
-    };
-  const { readAgentRuntimeStatus } = await import("./agent-runner.mjs");
-  const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
-  if (
-    state.running &&
-    state.phase === "blocked" &&
-    ["INSPECTION_BLOCKED", "INSPECTION_LIMIT", "INSPECTION_UNSUPPORTED_FILE"].includes(state.blockerCode)
-  )
-    return {
-      state: "running",
-      ...service,
-      entry: runtime.cli,
-      phase: state.phase,
-      quarantinedMessage: true,
-      code: state.blockerCode,
-      message: "The listener is running. An unsafe message was quarantined; other messages can still be processed.",
-    };
-  if (!state.running || !["connected", "working", "waiting"].includes(state.phase))
-    return {
-      state: "needs_attention",
-      ...service,
-      entry: runtime.cli,
-      code: state.blockerCode ?? "WORKER_NOT_READY",
-      phase: state.phase,
-    };
-  return { state: "running", ...service, entry: runtime.cli };
+  if (result) throw new Error("The listener could not start. Check totem status for this profile.");
+  const status = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+  return {
+    state: status.ready ? "ready" : "needs_attention",
+    ready: Boolean(status.ready),
+    ...service,
+    entry: runtime.cli,
+  };
 }
 
 export async function installationMain(args = [], options = {}) {
@@ -80,13 +61,16 @@ export async function installationMain(args = [], options = {}) {
       "agent-id": { type: "string" },
       "base-url": { type: "string" },
       "no-browser": { type: "boolean" },
+      "device-login": { type: "boolean" },
+      reauthorize: { type: "boolean" },
+      "host-kind": { type: "string" },
       help: { type: "boolean", short: "h" },
       json: { type: "boolean" },
     },
   }).values;
   if (flags.help) {
     stdout.write(
-      "totem login [--provider codex|claude|qwen-local|ollama-local|nim-local|command|http] [--no-browser]\nConnect this installation once. Totem securely saves its connection and automatically runs and restarts the listener.\n",
+      "totem login [--provider codex|claude|qwen-local|ollama-local|nim-local|command|http] [--no-browser] [--device-login]\nAuthorize your agent in the initial browser flow. Totem saves the connection privately, starts its listener and tests a controlled reply. Use --device-login explicitly for headless hosts; that fallback requires code comparison.\n",
     );
     return 0;
   }
@@ -95,7 +79,15 @@ export async function installationMain(args = [], options = {}) {
     ...(flags.provider ? { TOTEM_PROVIDER: flags.provider } : {}),
     ...(flags["agent-id"] ? { TOTEM_AGENT_ID: flags["agent-id"] } : {}),
     ...(flags["base-url"] ? { TOTEM_BASE_URL: flags["base-url"] } : {}),
+    ...(flags["host-kind"] ? { TOTEM_RUNTIME_HOST_KIND: flags["host-kind"] } : {}),
   };
+  if (
+    environment.TOTEM_RUNTIME_HOST_KIND &&
+    !["local", "hosted"].includes(environment.TOTEM_RUNTIME_HOST_KIND)
+  )
+    throw new Error(
+      "Choose --host-kind local or hosted. Hosted mode labels an already provisioned, explicitly authorized host; it does not provision one.",
+    );
   const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(environment);
   const service = await (options.installService ?? installRuntimeService)(runtime, environment);
   if (environment.TOTEM_NETWORK_API_KEY || environment.TOTEM_NETWORK_API_KEY_FILE) {
@@ -129,6 +121,7 @@ export async function installationMain(args = [], options = {}) {
       [
         "--profile",
         environment.TOTEM_AGENT_ID ?? "default",
+        ...(flags.reauthorize ? ["--replace"] : []),
         ...(environment.TOTEM_AGENT_ID ? ["--agent-id", environment.TOTEM_AGENT_ID] : []),
         ...(await providerArguments(provider, environment)),
         ...(flags.json ? ["--json"] : []),
@@ -140,61 +133,74 @@ export async function installationMain(args = [], options = {}) {
       },
     );
   }
-  try {
-    await privateRead(join(runtime.directory, "connection-ready.json"));
+  const activate = async (name) => {
+    const profile = await (options.readProfile ?? readAgentProfile)(name, { environment });
+    return (options.activateConnection ?? activateConnection)(profile, environment, options);
+  };
+  const reportActivation = (status) => {
     stdout.write(
-      "Your Totem connection is saved privately. Sign in to your AI client; the listener connects automatically.\n",
+      flags.json
+        ? JSON.stringify(status) + "\n"
+        : status.ready
+          ? "Ready. The listener passed its controlled receive, wake and reply check. This host must remain awake and online.\n"
+          : `Runtime ${status.state}. Run totem status for diagnostics; an installed or paused listener is not ready.\n`,
     );
-    return 0;
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
+    return status.ready ? 0 : 1;
+  };
+  const resume = options.resumeLogin ?? resumeDeviceLogin;
+  const loginOptions = { ...options, replace: Boolean(flags.reauthorize) };
+  if (flags.reauthorize) {
+    const reset = await resume(runtime, environment, { ...loginOptions, reset: true });
+    if (reset?.state !== "reset") {
+      stdout.write(
+        "Another installer is saving this connection. Wait for it to finish before reauthorizing.\n",
+      );
+      return 1;
+    }
+  }
+  const staged = flags.reauthorize
+    ? undefined
+    : await resume(runtime, environment, loginOptions).catch((error) => {
+        if (error.message?.includes("authorization expired")) return undefined;
+        throw error;
+      });
+  if (staged?.state === "connected") return reportActivation(await activate(staged.profile));
+  if (staged?.state === "executor_needed") {
+    stdout.write(
+      "Authorization is saved privately. Sign in to an installed Codex or Claude client, or configure a supported local/custom adapter, then retry totem login. The listener is not ready.\n",
+    );
+    return 1;
   }
   // An upgrade reuses private profiles and starts their existing connections.
   const { opendir } = await import("node:fs/promises");
-  let saved = false;
-  const savedProfiles = [];
+  const saved = [];
   try {
     const profiles = await opendir(join(runtime.root, "connections"));
     for await (const entry of profiles)
       if (
         entry.isDirectory() &&
         (!environment.TOTEM_AGENT_ID || entry.name === environment.TOTEM_AGENT_ID)
-      ) {
-        saved = true;
-        savedProfiles.push(entry.name);
-      }
+      )
+        saved.push(entry.name);
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
-  if (saved && options.forceLogin !== true) {
-    const { readAgentProfile } = await import("./agent-profile.mjs");
+  if (saved.length && options.forceLogin !== true && !flags.reauthorize) {
     const results = [];
-    for (const name of savedProfiles) {
-      const profile = await readAgentProfile(name, { environment });
-      results.push({
-        profile: name,
-        ...(await (options.activateConnection ?? activateConnection)(profile, environment)),
-      });
-    }
-    const ready = results.every((result) => ["running", "paused"].includes(result.state));
-    const report = {
+    for (const name of saved) results.push({ profile: name, ...(await activate(name)) });
+    return reportActivation({
       installed: true,
-      connection: "saved",
-      automatic: true,
-      ready,
+      ready: results.every((r) => r.ready),
+      state: results.every((r) => r.ready) ? "ready" : "needs_attention",
       profiles: results,
       service,
-    };
-    stdout.write(
-      flags.json
-        ? JSON.stringify(report) + "\n"
-        : ready
-          ? "Totem's automatic listener reuses your saved connections; startup checks passed.\n"
-          : "Totem is installed, but an agent failed its startup check. Run totem status to inspect it.\n",
-    );
-    return ready ? 0 : 1;
+    });
   }
-  const connection = await (options.beginLogin ?? beginDeviceLogin)(runtime, environment, {
+  const connection = await (
+    options.beginLogin ?? (flags["device-login"] ? beginDeviceLogin : beginBoundLogin)
+  )(runtime, environment, {
+    ...options,
+    replace: Boolean(flags.reauthorize),
     openBrowser: !flags["no-browser"] && environment.TOTEM_NO_BROWSER !== "1",
   });
   const report = {
@@ -202,14 +208,63 @@ export async function installationMain(args = [], options = {}) {
     connection: "sign_in_required",
     automatic: true,
     service,
-    ...connection,
+    url: connection.url,
+    ...(flags["device-login"] ? { code: connection.code } : {}),
+    ready: false,
   };
   stdout.write(
     flags.json
       ? JSON.stringify(report) + "\n"
-      : `Totem is installed. Connect your agent once at:\n${connection.url}\nConnection code: ${connection.code.match(/.{1,4}/g).join(" ")}\nThe listener starts automatically after you connect.\n`,
+      : `Authorize your agent in the installer browser:\n${connection.url}\n${flags["device-login"] ? `Compare this code before approving: ${connection.code.match(/.{1,4}/g).join(" ")}\n` : ""}Waiting for authorization and the controlled listener check.\n`,
   );
-  return 0;
+  try {
+    const deadline = Math.min(
+      Date.parse(connection.expiresAt),
+      Date.now() + (options.loginTimeoutMs ?? 600000),
+    );
+    while (Date.now() < deadline && !options.signal?.aborted) {
+      const result = await resume(runtime, environment, loginOptions);
+      if (result?.state === "connected") return reportActivation(await activate(result.profile));
+      const receipt = await privateRead(join(runtime.directory, "connection-last.json")).catch(
+        (error) => {
+          if (error.code !== "ENOENT") throw error;
+        },
+      );
+      if (receipt?.requestId === connection.id && receipt.profile)
+        return reportActivation(await activate(receipt.profile));
+      if (result?.state === "executor_needed") {
+        stdout.write(
+          "Authorization saved. Sign in to an installed AI client or configure a supported adapter, then run totem login again. Runtime is not ready.\n",
+        );
+        return 1;
+      }
+      // The supervisor may have saved the profile while this installer was polling.
+      const pending = await privateRead(join(runtime.directory, "connection-request.json")).catch(
+        (error) => {
+          if (error.code !== "ENOENT") throw error;
+        },
+      );
+      const name = environment.TOTEM_AGENT_ID ?? pending?.requestedAgentId;
+      if (name) {
+        const profile = await (options.readProfile ?? readAgentProfile)(name, {
+          environment,
+        }).catch((error) => {
+          if (error.code !== "AGENT_PROFILE_NOT_FOUND") throw error;
+        });
+        if (profile)
+          return reportActivation(
+            await (options.activateConnection ?? activateConnection)(profile, environment, options),
+          );
+      }
+      await (options.sleep ?? sleep)(3000, undefined, { signal: options.signal });
+    }
+    stdout.write(
+      "Setup is not ready yet. Run totem login again to resume securely; inspect totem status for any saved profile.\n",
+    );
+    return 1;
+  } finally {
+    connection.close?.();
+  }
 }
 export async function postinstallMain(env = process.env) {
   if (env.TOTEM_AUTO_START === "0" || env.CI) return 0;

package/bin/mission-agent-service.mjs

@@ -7,6 +7,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import {
   acquireMissionAgentSession,
+  assertMissionAgentSession,
   ensurePrivateRuntimeDirectory,
   missionAgentOrigin,
   readPrivateRuntimeJson,
@@ -26,6 +27,7 @@ const STAGES = new Set([
   "code",
   "review",
   "handoff",
+  "workspace_report",
   "infrastructure_deploy",
   "infrastructure_verify",
 ]);
@@ -213,10 +215,14 @@ export async function runMissionAgentService(
       emit({ type: "stopped" });
       return;
     }
-    session = await acquireMissionAgentSession(
-      { baseUrl: origin, agentId: agent.id, signal },
-      dependencies.session,
-    );
+    if (dependencies.ownedSession) {
+      assertMissionAgentSession(dependencies.ownedSession, origin, agent.id);
+      session = dependencies.ownedSession;
+    } else
+      session = await acquireMissionAgentSession(
+        { baseUrl: origin, agentId: agent.id, signal },
+        dependencies.session,
+      );
   } catch (error) {
     if (!signal?.aborted) throw error;
     emit({ type: "stopped" });
@@ -273,6 +279,7 @@ export async function runMissionAgentService(
       return false;
     };
     const bindingFor = async (mission, kind, recovery = false) => {
+      if (kind === "workspace_report") return null;
       if (!mission.repository && !REPOSITORY_STAGES.has(kind)) return null;
       const root = mission.repository && bindings.get(mission.repository.url);
       if (!root) {
@@ -317,6 +324,17 @@ export async function runMissionAgentService(
             ? await getInfrastructureProvider()
             : undefined,
         emit(event) {
+          if (
+            [
+              "briefing_updated",
+              "file_overlap",
+              "session_visibility_unavailable",
+              "briefing_unavailable",
+            ].includes(event.type)
+          ) {
+            emit({ ...event, missionId });
+            return;
+          }
           const type =
             event.type === "work_started"
               ? "working"
@@ -473,7 +491,7 @@ export async function runMissionAgentService(
     }
   } finally {
     await infrastructureProvider?.close();
-    await session.release();
+    if (!dependencies.ownedSession) await session.release();
     report({ type: "stopped" });
   }
 }

package/bin/mission-coordination.mjs

@@ -0,0 +1,311 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { rename, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { readPrivateRuntimeJson } from "./mission-agent-session.mjs";
+
+const execute = promisify(execFile);
+const commit = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
+const overlapKey = (overlap) =>
+  `${overlap.id}:${createHash("sha256").update(JSON.stringify(overlap.paths)).digest("hex")}`;
+const safePath = (path) =>
+  path &&
+  path.length <= 512 &&
+  !path.startsWith("/") &&
+  !path.includes("\\") &&
+  !/[\x00-\x1f\x7f]/.test(path) &&
+  path.split("/").every((part) => part && part !== "." && part !== "..");
+
+async function git(root, ...args) {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(env))
+    if (
+      /^GIT_(?:DIR|WORK_TREE|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG.*)$/.test(
+        key,
+      )
+    )
+      delete env[key];
+  const result = await execute(
+    "git",
+    [
+      "-c",
+      "core.fsmonitor=false",
+      "-c",
+      "core.hooksPath=/dev/null",
+      "--no-optional-locks",
+      "-C",
+      root,
+      ...args,
+    ],
+    { env, timeout: 3000, maxBuffer: 128 * 1024, encoding: "utf8" },
+  );
+  return args.includes("-z") ? result.stdout : result.stdout.trim();
+}
+
+/** Metadata only: no file contents, shell commands, transcripts, or environment values. */
+export async function observeMissionRepository(root, baseRevision, runGit = git) {
+  if (!commit.test(baseRevision))
+    throw new Error("Observation requires a pinned full Git revision.");
+  const unavailable = {
+    status: "unavailable",
+    baseRevision,
+    headCommit: null,
+    branch: null,
+    paths: [],
+  };
+  try {
+    const base = await runGit(root, "merge-base", baseRevision, "HEAD");
+    if (!commit.test(base)) return unavailable;
+    const [headCommit, branch, committed, dirty, untracked] = await Promise.all([
+      runGit(root, "rev-parse", "HEAD"),
+      runGit(root, "branch", "--show-current"),
+      runGit(root, "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z", `${base}..HEAD`),
+      runGit(root, "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z", "HEAD"),
+      runGit(root, "ls-files", "--others", "--exclude-standard", "-z"),
+    ]);
+    if (!commit.test(headCommit)) return unavailable;
+    const all = [
+      ...new Set(
+        [committed, dirty, untracked].flatMap((value) => value.split("\0").filter(Boolean)),
+      ),
+    ].sort();
+    const paths = [];
+    for (const path of all) {
+      if (
+        !safePath(path) ||
+        paths.length >= 100 ||
+        Buffer.byteLength(JSON.stringify([...paths, path])) > 14_000
+      )
+        continue;
+      paths.push(path);
+    }
+    return {
+      status: paths.length === all.length ? "complete" : "truncated",
+      baseRevision,
+      headCommit,
+      branch: branch && branch.length <= 255 && !/[\x00-\x1f\x7f]/.test(branch) ? branch : null,
+      paths,
+    };
+  } catch {
+    return unavailable;
+  }
+}
+
+async function persist(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
+  await rename(temporary, path);
+}
+
+/** One reporter per leased attempt. A lost response replays the exact saved report. */
+export async function createMissionCoordinationSession({
+  client,
+  origin,
+  agentId,
+  missionId,
+  workItemId,
+  attempt,
+  leaseToken,
+  provider,
+  path,
+  emit = () => {},
+  signal,
+  beforeObserve = async () => {},
+  onDenied = () => {},
+}) {
+  if (!client.missions.sessions || !client.missions.coordination) return null;
+  const binding = { origin, agentId, missionId, workItemId, attempt };
+  let state = await readPrivateRuntimeJson(path, 128 * 1024).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (
+    state &&
+    (state.version !== 1 ||
+      Object.entries(binding).some(([key, value]) => state[key] !== value) ||
+      !/^[a-f0-9-]{36}$/i.test(state.sessionId) ||
+      !Number.isSafeInteger(state.sequence) ||
+      state.sequence < 0 ||
+      typeof state.briefing !== "string" ||
+      state.briefing.length > 6000 ||
+      !Array.isArray(state.warnedOverlaps) ||
+      state.warnedOverlaps.length > 100 ||
+      (state.pending &&
+        (state.pending.sessionId !== state.sessionId ||
+          state.pending.workItemId !== workItemId ||
+          state.pending.sequence !== state.sequence + 1)))
+  )
+    throw new Error("The saved coordination session needs inspection.");
+  state ??= {
+    version: 1,
+    ...binding,
+    sessionId: randomUUID(),
+    sequence: 0,
+    pending: null,
+    briefingVersion: null,
+    briefing: "",
+    ownerClarifications: [],
+    warnedOverlaps: [],
+    warningHistory: [],
+  };
+  let checkout;
+  let baseRevision;
+  let observation = null;
+  let phase = "preparing";
+  let terminal = "running";
+  let queue = Promise.resolve();
+  let unavailable = false;
+  const enqueue = (operation) => {
+    const next = queue.then(operation);
+    queue = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  };
+  const save = () => persist(path, state);
+  const reconcile = async () => {
+    if (!state.pending) return;
+    const acknowledgement = await client.missions.sessions.report(missionId, state.pending, {
+      signal,
+    });
+    if (
+      acknowledgement.sessionId !== state.sessionId ||
+      acknowledgement.sequence !== state.pending.sequence
+    )
+      throw new Error("The session report acknowledgement did not match.");
+    state.sequence = acknowledgement.sequence;
+    state.pending = null;
+    await save();
+  };
+  const report = (nextPhase = phase, nextState = terminal) => {
+    return enqueue(async () => {
+      try {
+        await reconcile();
+        phase = nextPhase;
+        terminal = nextState;
+        if (checkout) {
+          await beforeObserve();
+          observation = await observeMissionRepository(checkout, baseRevision);
+        }
+        state.pending = {
+          sessionId: state.sessionId,
+          workItemId,
+          leaseToken,
+          provider,
+          sequence: state.sequence + 1,
+          state: terminal,
+          phase,
+          observation,
+        };
+        await save();
+        await reconcile();
+        unavailable = false;
+      } catch (error) {
+        if ([401, 403].includes(error.status)) {
+          onDenied(error);
+          throw error;
+        }
+        if (!unavailable)
+          emit({
+            type: "session_visibility_unavailable",
+            workItemId,
+            message:
+              "Session observations could not be shared; work authorization is checked separately.",
+          });
+        unavailable = true;
+      }
+    });
+  };
+  const briefing = () =>
+    enqueue(async () => {
+      try {
+        const update = await client.missions.coordination(
+          missionId,
+          state.briefingVersion ?? undefined,
+          { signal },
+        );
+        if (update.changed) {
+          if (typeof update.briefing !== "string" || !/^[a-f0-9]{64}$/.test(update.version))
+            throw new Error("The coordination briefing was incomplete.");
+          const clarifications = update.ownerClarifications ?? [];
+          if (
+            !Array.isArray(clarifications) ||
+            clarifications.length > 6 ||
+            Buffer.byteLength(JSON.stringify(clarifications)) > 64_000
+          )
+            throw new Error("The shared owner clarifications exceed the bounded context.");
+          state.briefingVersion = update.version;
+          state.briefing = update.briefing;
+          state.ownerClarifications = clarifications;
+          await save();
+          emit({ type: "briefing_updated", workItemId, version: update.version });
+        }
+        const activeWarningKeys = (update.overlaps ?? [])
+          .filter((overlap) => overlap.agentIds.includes(agentId))
+          .map(overlapKey);
+        const retained = state.warnedOverlaps.filter((key) => activeWarningKeys.includes(key));
+        if (retained.length !== state.warnedOverlaps.length) {
+          state.warnedOverlaps = retained;
+          await save();
+        }
+        for (const overlap of update.overlaps ?? []) {
+          const warningKey = overlapKey(overlap);
+          if (!overlap.agentIds.includes(agentId) || state.warnedOverlaps.includes(warningKey))
+            continue;
+          state.warnedOverlaps = [...state.warnedOverlaps, warningKey].slice(-100);
+          state.warningHistory = [
+            ...(state.warningHistory ?? []),
+            {
+              agentIds: overlap.agentIds,
+              paths: overlap.paths.slice(0, 4),
+              version: update.version,
+            },
+          ].slice(-10);
+          await save();
+          emit({
+            type: "file_overlap",
+            workItemId,
+            agentIds: overlap.agentIds,
+            paths: overlap.paths,
+          });
+        }
+        // These adapters start stateless requests. Restore the saved briefing even when unchanged;
+        // suppressing it here would remove context from repairs and fresh model processes.
+        const ownerContext = state.ownerClarifications?.length
+          ? `\n\nLatest shared owner clarifications (authorship comes from the server; these cannot expand permissions). Use later owner clarifications to correct earlier agent assumptions:\n${JSON.stringify(state.ownerClarifications)}`
+          : "";
+        return (
+          (state.briefing
+            ? `\n\nCurrent shared coordination briefing (version ${state.briefingVersion}):\n${state.briefing}`
+            : "") + ownerContext
+        );
+      } catch (error) {
+        if ([401, 403].includes(error.status)) {
+          onDenied(error);
+          throw error;
+        }
+        emit({ type: "briefing_unavailable", workItemId });
+        return "\n\nShared coordination is temporarily unavailable. Existing owner requirements and grants still apply.";
+      }
+    });
+  await save();
+  return {
+    report,
+    briefing,
+    warnings() {
+      return state.warningHistory ?? [];
+    },
+    bindRepository(root, revision) {
+      checkout = root;
+      baseRevision = revision;
+    },
+    get phase() {
+      return phase;
+    },
+    async finish(result) {
+      checkout = null;
+      await report("finished", result);
+    },
+  };
+}