@runuai/host 0.9.166 → 0.9.168

package/lib/orchestrator.ts

@@ -1,3 +1,11 @@
+import { randomUUID } from "node:crypto";
+import { AssignmentEvidenceJournal } from "./assignment-evidence";
+import { durableAgentSessionId } from "./agents/transport";
+import { agentOutputSource } from "./agents/output-source";
+import { taskDir } from "./env";
+import { readTaskRunEpochState } from "./runtime-state";
+import type { AssignmentDelivery, AssignmentTurnEvidence } from "../src/protocol";
+
 /**
  * Orchestrator — the chat channel runtime.
  *
@@ -292,6 +300,7 @@ interface Channel {
   /** ADR-083: host-derived role assignment for execution-profile enforcement. */
   mode: "open" | "secretary";
   secretaryAgentId?: string;
+  leadRunId?: string | null;
   sessions: Map<string, AgentSession>;
   /** Session-spawn inputs, kept so sessions can be started lazily. */
   containerName: string;
@@ -386,10 +395,10 @@ interface Channel {
    *  boundary. Adapters do not share one mid-turn input contract, so only this
    *  cross-lane role is serialized at the host boundary; open mode keeps its
    *  legacy immediate-concurrent delivery behavior. */
-  pendingPrompts: Map<string, string[]>;
+  pendingPrompts: Map<string, AcceptedPrompt[]>;
   /** Prompts accepted by channelDeliver whose final session boundary rejected
    * specifically because the container runtime became unavailable. */
-  runtimeDeferredPrompts: Map<string, string[]>;
+  runtimeDeferredPrompts: Map<string, AcceptedPrompt[]>;
   /** Missing/blocked sessions to reconcile exactly once after runtime ready. */
   runtimeDeferredAgents: Set<string>;
   /** Agents whose current turn was interrupted (ESC) — their next
@@ -471,7 +480,7 @@ interface Channel {
   accountByAgent: Map<string, string>;
   /** ADR-076: the last prompt delivered to each agent, re-sent after an
    *  account rotation so the interrupted turn resumes on the new account. */
-  lastPrompt: Map<string, string>;
+  lastPrompt: Map<string, AcceptedPrompt>;
   /** ADR-076: per-agent account-rotation budget (reset on a successful turn) —
    *  bounds a rate-limit storm across accounts, mirroring the respawn budget. */
   rotations: Map<string, number>;
@@ -537,8 +546,27 @@ function mcpAgentMembershipFingerprint(
   );
 }
 
+const evidenceSessionIds = new WeakMap<AgentSession, string>();
+function evidenceSessionId(taskId: string, agentId: string, session: AgentSession): string {
+  let id = evidenceSessionIds.get(session);
+  if (!id) {
+    // Pin to this session object, including its final/aborted boundary. The
+    // registry may already contain its replacement by the time output ends.
+    id = durableAgentSessionId(taskId, agentId) ?? randomUUID();
+    evidenceSessionIds.set(session, id);
+  }
+  return id;
+}
+const evidenceRuntimeVersion: string | null = (() => {
+  try { return (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version; }
+  catch { return null; }
+})();
+
 interface AcceptedPrompt {
   text: string;
+  /** Frozen at acceptance. Null means unallocated, not inherit the latest. */
+  assignment: AssignmentDelivery | null;
+  leadRunId?: string | null;
 }
 
 interface RosterSessionChange {
@@ -927,6 +955,16 @@ export class Orchestrator {
   }
 
   private emitHost(event: HostEvent): void {
+    if (event.kind === "agent.message_complete" || event.kind === "agent.turn_complete") {
+      const session = this.channels.get(event.taskId)?.sessions.get(event.agentId);
+      const path = join(taskDir(event.taskId), ".uai", "assignment-evidence", `${event.agentId}.json`);
+      if (session && existsSync(path)) {
+        const evidence = new AssignmentEvidenceJournal(path).observe(
+          evidenceSessionId(event.taskId, event.agentId, session), agentOutputSource.getStore() ? agentOutputSource.getStore() + ":" + event.kind : undefined, event.kind === "agent.turn_complete",
+        );
+        if (evidence) event = { ...event, evidence };
+      }
+    }
     for (const fn of this.hostSubscribers) {
       try {
         fn(event);
@@ -1090,6 +1128,7 @@ export class Orchestrator {
     channel.humans = spec.humans ?? [];
     channel.mode = spec.mode === "secretary" ? "secretary" : "open";
     channel.secretaryAgentId = spec.secretaryAgentId;
+    channel.leadRunId = spec.leadRunId ?? null;
     channel.browserTesting = spec.browserTesting === true;
     if (channel.browserTesting) {
       const affectedKinds = browserWasEnabled
@@ -1390,6 +1429,7 @@ export class Orchestrator {
         HOST_ACCOUNT_SCOPE,
       mode: spec.mode === "secretary" ? "secretary" : "open",
       secretaryAgentId: spec.secretaryAgentId,
+      leadRunId: spec.leadRunId ?? null,
       sessions: new Map(),
       containerName: `task-${taskId.toLowerCase()}-app-1`,
       agentEnvironment: null,
@@ -2667,6 +2707,7 @@ export class Orchestrator {
                   task.ownerUserId,
                   apiUrl,
                   cliSecret,
+                this.isSecretary(channel, agent.id) ? channel.leadRunId : null,
                 ),
                 task,
               ),
@@ -4450,6 +4491,7 @@ export class Orchestrator {
                 task.ownerUserId,
                 apiUrl,
                 cliSecret,
+                this.isSecretary(channel, agent.id) ? channel.leadRunId : null,
               ),
               task,
             ),
@@ -4686,28 +4728,48 @@ export class Orchestrator {
     channel: Channel,
     agentId: string,
     session: AgentSession,
-    prompt: string,
+    prompt: string | AcceptedPrompt,
+    assignment?: AssignmentDelivery,
   ): void {
+    const replay = typeof prompt !== "string";
+    const text = typeof prompt === "string" ? prompt : prompt.text;
+    const leadRunId = replay ? (prompt as AcceptedPrompt).leadRunId ?? null : this.isSecretary(channel, agentId) ? channel.leadRunId ?? null : null;
+    const originalAssignment = typeof prompt === "string" ? (this.isSecretary(channel, agentId) ? null : assignment) : prompt.assignment;
+    let retainedAssignment = originalAssignment ?? null;
+    const journalPath = join(taskDir(channel.taskId), ".uai", "assignment-evidence", `${agentId}.json`);
+    let turn: AssignmentTurnEvidence | undefined;
+    const journal = assignment || leadRunId || existsSync(journalPath) ? new AssignmentEvidenceJournal(journalPath) : null;
+    const sessionId = evidenceSessionId(channel.taskId, agentId, session);
+    if (journal) {
+      const begun = journal.begin({ sessionId, engine: session.kind,
+        runEpoch: readTaskRunEpochState(channel.taskId)?.highestRunEpoch ?? 0,
+        recipientGeneration: channel.roster.find(a => a.id === agentId)?.tokenGeneration ?? null,
+        runtimeVersion: evidenceRuntimeVersion, assignment: originalAssignment, replay, leadRunId });
+      if (!begun) return; // stable assignment replay, already accepted
+      turn = begun;
+      retainedAssignment = begun.assignment;
+    }
     // ADR-076: this is the prompt actually in flight. A queued follow-up must
     // not replace it or account rotation would replay the wrong turn.
-    channel.lastPrompt.set(agentId, prompt);
-    const accepted = { text: prompt };
+    const accepted: AcceptedPrompt = { text, assignment: retainedAssignment, leadRunId };
+    channel.lastPrompt.set(agentId, accepted);
     const acceptedForAgent = channel.acceptedPrompts.get(agentId) ?? [];
     acceptedForAgent.push(accepted);
     channel.acceptedPrompts.set(agentId, acceptedForAgent);
     this.incrementActiveTurns(channel, agentId);
-    void session.send(prompt).catch((err: unknown) => {
+    void session.send(text).catch((err: unknown) => {
+      if (turn) journal?.failed(sessionId, turn.turnId);
       if (channel.sessions.get(agentId) === session) {
         this.removeAcceptedPrompt(channel, agentId, accepted);
         const remaining = this.decrementActiveTurns(channel, agentId);
         if (
           remaining === 0 &&
-          channel.lastPrompt.get(agentId) === prompt
+          channel.lastPrompt.get(agentId) === accepted
         ) {
           channel.lastPrompt.delete(agentId);
         }
         if (err instanceof ContainerRuntimeUnavailableError) {
-          this.deferPromptUntilRuntimeReady(channel, agentId, prompt);
+          this.deferPromptUntilRuntimeReady(channel, agentId, accepted);
         } else {
           this.startNextPendingPrompt(channel, agentId);
         }
@@ -4745,7 +4807,7 @@ export class Orchestrator {
   private deferPromptUntilRuntimeReady(
     channel: Channel,
     agentId: string,
-    prompt: string,
+    prompt: AcceptedPrompt,
   ): void {
     channel.runtimeDeferredAgents.add(agentId);
     if (this.isSecretary(channel, agentId)) {
@@ -4810,6 +4872,7 @@ export class Orchestrator {
     /** ADR-141 rung 1: only a human turn is shadow-routed. An older cloud
      *  sends nothing, which reads as "not human" and keeps the pass off. */
     origin?: DeliveryOrigin,
+    assignment?: AssignmentDelivery,
   ): Promise<{ ok: true } | { ok: false; error: string }> {
     // Slash command: re-run GitHub auth setup for this task (ADR-027). Handled
     // before sessions so it works even when an agent isn't ready.
@@ -4829,11 +4892,15 @@ export class Orchestrator {
     const session = channel.sessions.get(agentId);
     if (!session) return { ok: false, error: `no such agent: ${agentId}` };
 
+    if (assignment && (assignment.runEpoch !== (readTaskRunEpochState(taskId)?.highestRunEpoch ?? 0) ||
+      assignment.recipientGeneration !== (channel.roster.find(a => a.id === agentId)?.tokenGeneration ?? null))) {
+      return { ok: false, error: "assignment belongs to another run or agent generation" };
+    }
     const prompt = rewriteAttachmentRefs(text);
     if (this.isSecretary(channel, agentId)) {
       const queue = channel.pendingPrompts.get(agentId) ?? [];
       if ((channel.activeTurns.get(agentId) ?? 0) > 0 || queue.length > 0) {
-        queue.push(prompt);
+        queue.push({ text: prompt, assignment: assignment ?? null, leadRunId: channel.leadRunId ?? null });
         channel.pendingPrompts.set(agentId, queue);
         // A replacement session may have bound after the queue was observed
         // but before this delivery. Preserve FIFO by starting the oldest item.
@@ -4845,7 +4912,7 @@ export class Orchestrator {
       // Preserve the legacy open-room contract: adapters receive concurrent
       // deliveries immediately. Only the designated Secretary needs the hard
       // turn boundary because crew replies can arrive during its dispatch turn.
-      this.startPrompt(channel, agentId, session, prompt);
+      this.startPrompt(channel, agentId, session, prompt, assignment);
     }
     // ADR-141 rung 1: after the turn is on its way, ask what Auto would have
     // done and report it. Fire-and-forget by design — it must never delay or
@@ -5409,12 +5476,26 @@ export class Orchestrator {
         // ADR-076: a turn that completed means the current account is healthy —
         // reset its rotation budget so a LATER rate-limit gets a fresh failover.
         channel.rotations.delete(agentId);
+        // Name the leased AI account on the turn usage report so the cloud
+        // ledger can roll up observed spend per credential (host 0.9.167+).
+        // Only a cloud-leased account identity is reportable; runner-default
+        // and Managed Engine identities stay unnamed (same rule as account_usage).
+        const leasedIdentity = channel.leasedIdentityByAgent.get(agentId);
+        const usage =
+          event.usage === undefined
+            ? undefined
+            : {
+                ...event.usage,
+                ...(leasedIdentity?.subject === "account"
+                  ? { credentialId: leasedIdentity.credentialId }
+                  : {}),
+              };
         this.emitHost({
           kind: "agent.turn_complete",
           taskId: channel.taskId,
           agentId,
           aborted,
-          usage: event.usage,
+          usage,
         });
         if (remainingTurns === 0) {
           channel.lastPrompt.delete(agentId);
@@ -5487,7 +5568,12 @@ export class Orchestrator {
   /** An engine error can race a live launch edit after a partial turn. Keep
    * the obsolete adapter owned until the stale recycler closes it, but close
    * the cloud turn boundary immediately so restarting/ready cannot leave the
-   * crew UI stuck in a working state. */
+   * crew UI stuck in a working state.
+   *
+   * The error is still reported, as the exit notice every other engine error
+   * sends: whatever the agent was doing is lost, and without it nobody (the
+   * human, or a Secretary waiting on the agent) was told why. Sent before the
+   * reconcile below, so the cloud sees it ahead of the respawn's `restarting`. */
   private reconcileErroredRosterChange(
     channel: Channel,
     agentId: string,
@@ -5501,6 +5587,12 @@ export class Orchestrator {
       if (change) this.publishRosterChangeAbort(channel, agentId, change);
       else this.emitRetiredTurnAbort(channel, agentId);
     }
+    this.emitHost({
+      kind: "agent.exit",
+      taskId: channel.taskId,
+      agentId,
+      reason,
+    });
     void this.reconcileAfterRosterRefresh(channel).catch((err: unknown) => {
       console.warn(
         `[orchestrator] ${channel.taskId}/${agentId}: roster-change error (${reason}) reconcile failed: ${
@@ -5536,7 +5628,7 @@ export class Orchestrator {
     channel.lastPrompt.delete(agentId);
     if (accepted.length > 0 && !interrupted) {
       for (const prompt of accepted) {
-        this.deferPromptUntilRuntimeReady(channel, agentId, prompt.text);
+        this.deferPromptUntilRuntimeReady(channel, agentId, prompt);
       }
     } else {
       // Recreate even an idle session after readiness, without fabricating a
@@ -5670,6 +5762,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isSecretary(channel, agent.id) ? channel.leadRunId : null,
       );
       const boundAccountId = channel.accountByAgent.get(agentId);
       const boundAccount = boundAccountId
@@ -5884,6 +5977,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isSecretary(channel, agent.id) ? channel.leadRunId : null,
       );
       channel.accountByAgent.set(agentId, next.id);
       noteEngineAccountUsed(next.id);
@@ -6093,6 +6187,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isSecretary(channel, agent.id) ? channel.leadRunId : null,
       );
       channel.accountByAgent.set(agentId, account.id);
       noteEngineAccountUsed(account.id);
@@ -7459,7 +7554,13 @@ export function buildSystemPreamble(
           `\`${(agent.permissions ?? []).join(", ")}\`. Commands: \`projects list\`,`,
           "`people list`, `task list`" +
             (agent.permissions?.includes("tasks.create")
-              ? ", `task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]`"
+              ? ", `task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle] [--astronaut engine/model/effort] [--start --request-id <logical-run-id>]`"
+              : "") +
+            (agent.permissions?.includes("tasks.read")
+              ? ", `task watch <childId> [--after <cursor>]`, `task usage <childId>`"
+              : "") +
+            (agent.permissions?.includes("tasks.chat")
+              ? ", `task send <childId> <text>`, `task answer <childId> <cardId> <option>`"
               : "") +
             (agent.permissions?.includes("tasks.close")
               ? ", `task close --status finished|canceled [--reason \"final report\"]`"
@@ -7495,8 +7596,13 @@ export function buildSystemPreamble(
                 `shell command \`node ${CONTAINER_CLI_PATH} task create …\`. Do NOT`,
                 "use your built-in TaskCreate / task tools for this — those are just",
                 "your own private to-do notes and are invisible to the human in Uai.",
-                "Uai tasks you create are DRAFTS — a human reviews and starts them;",
-                "nothing runs (or spends) until then. Discover options first with",
+                "Tasks you create are your own direct children, DRAFTS by default.",
+                "Only an explicit tasks.start grant lets --start launch them,",
+                "under the owner's limits and this task's account lane.",
+                "Only children you started are delegated to you; a live chat-capable Secretary receives coalesced events. Otherwise the child addresses the person.",
+                "Closing the parent leaves running children alive. Child permissions never exceed your live creation ceiling.",
+                "Send/answer are visibly delegated agent inputs, never human approval.",
+                "Discover options first with",
                 "`projects list` / `people list`.",
               ]
             : []),

package/lib/project-env-loader.ts

@@ -181,6 +181,7 @@ export function taskProjectEnvResolver(
     readonly placeholders: Readonly<Record<string, string>>;
   } = () => ({ withheld: [], placeholders: {} }),
   taskSource: () => TaskEnvSource = () => STORED,
+  taskSecrets: () => { revision: string; withheld: readonly string[]; values: Readonly<Record<string, string>> } = () => ({ revision: "", withheld: [], values: {} }),
 ): TaskGatewayEnvResolver {
   const projectIds = [...new Set(spec.projects.map((project) => project.projectId))];
   let revisions: number[] | undefined;
@@ -192,7 +193,9 @@ export function taskProjectEnvResolver(
     const currentUai = uaiEnv();
     const currentProxied = proxiedEnv();
     const currentSource = taskSource();
+    const secrets = taskSecrets();
     const currentRunnerKey = JSON.stringify([
+      secrets.revision,
       Object.entries(currentUai).sort(([a], [b]) => compareAscii(a, b)),
       [...currentProxied.withheld].sort(compareAscii),
       Object.entries(currentProxied.placeholders).sort(([a], [b]) => compareAscii(a, b)),
@@ -214,6 +217,7 @@ export function taskProjectEnvResolver(
     Object.assign(values, resolved.values);
     const withheld = new Set([
       ...currentProxied.withheld,
+      ...secrets.withheld,
       ...(currentSource.kind === "view" ? currentSource.view.notDelivered : []),
     ]);
     for (const name of withheld) delete values[name];
@@ -225,6 +229,7 @@ export function taskProjectEnvResolver(
         values[name] = placeholder;
       }
     }
+    Object.assign(values, secrets.values);
     for (const [name, value] of Object.entries(currentUai)) {
       // Only reserved names: Uai's own variables, never a project's.
       if (ENV_NAME.test(name) && isReservedTaskEnvName(name) && !value.includes("\0")) values[name] = value;

package/lib/secrets-proxy/policy.ts

@@ -1,3 +1,4 @@
+import { taskSecretsView } from "../credential-consumers/task-secrets";
 /**
  * Which keys each task has in proxy mode (ADR-153's effective policy: the
  * owner's binding ∩ the task's schema observation), and what of that the
@@ -36,21 +37,29 @@ export function createTaskProxyPolicySource(
   return {
     proxiedKeys: (taskId) => {
       if (!isServed(taskId)) return null;
-      return (viewOf(taskId)?.proxied ?? []).map(({ projectId, key, domains, placeholder, head }) => ({
+      const secrets = taskSecretsView(taskId);
+      const taskKeys = secrets.filter(s => s.manifest.mode === "proxied").map(s => ({ projectId: `task-secret:${taskId}`, key: s.manifest.name, domains: s.manifest.domains, placeholder: s.manifest.placeholder, head: { revision: s.manifest.generation, generation: s.manifest.generation, tombstone: false as const, valueRef: { kind: "staged" as const, stagingId: s.manifest.stagingId } } }));
+      return [...taskKeys, ...(viewOf(taskId)?.proxied ?? []).filter(e => !secrets.some(s => s.manifest.name === e.key)).map(({ projectId, key, domains, placeholder, head }) => ({
         projectId,
         key,
         domains,
         placeholder,
         head,
-      }));
+      }))];
     },
     realValue: (taskId, ref) => {
+      if (!isServed(taskId)) return null;
+      if (ref.projectId === `task-secret:${taskId}`) {
+        const secret = taskSecretsView(taskId).find(s => s.manifest.name === ref.key && s.manifest.mode === "proxied");
+        return secret && ref.head?.generation === secret.manifest.generation && ref.head.valueRef?.kind === "staged" && ref.head.valueRef.stagingId === secret.manifest.stagingId ? secret.material?.value ?? null : null;
+      }
+      if (taskSecretsView(taskId).some(s => s.manifest.name === ref.key)) return null;
       const { head } = ref;
       if (head === undefined) return null;
       const proxied = viewOf(taskId)?.proxied.find((entry) => entry.projectId === ref.projectId && entry.key === ref.key);
       return proxied !== undefined && sameTaskEnvHead(proxied.head, head) ? proxied.value : null;
     },
-    notDelivered: (taskId) => viewOf(taskId)?.notDelivered ?? null,
+    notDelivered: (taskId) => [...(viewOf(taskId)?.notDelivered ?? []), ...taskSecretsView(taskId).map(s => s.manifest.name)],
   };
 }
 

package/lib/standard-image.ts

@@ -67,7 +67,7 @@ export const ASDF_DATA_VOLUME = "uai-asdf-data";
 export const STANDARD_DEFAULT_NODE_VERSION = "22.11.0";
 
 /** Exact Codex CLI release exposed to task runtimes through the shared volume. */
-export const STANDARD_CODEX_CLI_VERSION = "0.157.0";
+export const STANDARD_CODEX_CLI_VERSION = "0.164.0";
 
 /**
  * Runtimes the standard image's asdf plugins can satisfy, with a sensible set

package/lib/task-env-source.ts

@@ -1,3 +1,4 @@
+import { deliveredTaskSecrets } from "./credential-consumers/task-secrets";
 /**
  * ADR-153 §4 and §6: where a task's project env comes from, for its /env and
  * its proxy alike, on an owned runner and on a task machine's sidecar.
@@ -233,6 +234,7 @@ export function taskEnvResolver(taskId: string, spec: TaskProjectEnvSpec, runEpo
     () => taskTrustEnv(taskId),
     () => taskProxiedEnv(taskId),
     () => taskEnvSource(taskId, spec, runEpoch),
+    () => deliveredTaskSecrets(taskId, runEpoch),
   );
 }
 

package/lib/task-project-ops-host.ts

@@ -0,0 +1,147 @@
+/**
+ * ADR-161 §2: the live-project commands wired to this runner's real state —
+ * the task's persisted environment, its run-epoch admission, its lifecycle
+ * slot, its lease grant and env replica, and its persisted env spec.
+ */
+
+import { activeCloudCredentials, credentialsMode } from "./cloud-credential-host";
+import { getOrchestrator } from "./orchestrator";
+import {
+  getHostTask,
+  hostTaskProjectEnvSpec,
+  readTaskRunEpochState,
+  taskProjectEnvSpec,
+  upsertHostTask,
+  type TaskProjectEnvSpec,
+} from "./runtime-state";
+import { taskUaiDir } from "./env";
+import { captureTaskEnvSchemaFromClone, taskEnvSchemaObservation } from "./project-env-schema-capture";
+import { reconstructPersistedTaskEnvironment } from "./task-environment";
+import { forgetTaskEnvSnapshot, taskEnvResolver } from "./task-env-source";
+import { currentTaskGatewayRegistration, setTaskGatewayEnvResolver } from "./task-gateway-state";
+import { TaskProjectJournalStore, TaskProjectOps } from "./task-project-ops";
+import type { TaskCommandProject } from "../src/protocol";
+
+function runIsCurrent(taskId: string, runEpoch: number): boolean {
+  const task = getHostTask(taskId);
+  if (!task || task.statusMirror !== "running") return false;
+  const state = readTaskRunEpochState(taskId);
+  // A task started before run epochs carries none; the cloud never sends
+  // these commands to it (it has no `live-task-projects-v1` contract).
+  return state !== null && state.assignmentOpen && state.highestRunEpoch === runEpoch;
+}
+
+/** Names the cloud's literal channel must never set live: the editor theme
+ *  is the task's, chosen at start. */
+const RESERVED_LITERAL_ENV = new Set(["UAI_EDITOR_THEME"]);
+
+/**
+ * One project (and its preview URL literals) added to a persisted env spec.
+ * Every other entry stays; a literal name the task already has keeps its
+ * value, as at start where the first project to declare one wins.
+ */
+export function specWithProject(
+  spec: TaskProjectEnvSpec,
+  project: TaskCommandProject,
+  previewEnv: Record<string, string> = {},
+): TaskProjectEnvSpec {
+  const hasProject = spec.projects.some((entry) => entry.projectId === project.id);
+  const addedLiterals = Object.entries(previewEnv).filter(
+    ([name]) => !RESERVED_LITERAL_ENV.has(name) && !(name in spec.previewEnv),
+  );
+  if (hasProject && addedLiterals.length === 0) return spec;
+  const [entry] = taskProjectEnvSpec({
+    projects: [project],
+    task: { previewEnv: {} } as Parameters<typeof taskProjectEnvSpec>[0]["task"],
+  }).projects;
+  return {
+    ...spec,
+    projects: hasProject
+      ? spec.projects
+      : [...spec.projects, entry!].sort(
+          (left, right) => left.position - right.position || left.projectId.localeCompare(right.projectId),
+        ),
+    previewEnv: Object.fromEntries(
+      [...Object.entries(spec.previewEnv), ...addedLiterals].sort(([left], [right]) => left.localeCompare(right)),
+    ),
+  };
+}
+
+function liveProjectsSupported(taskId: string): boolean {
+  const task = getHostTask(taskId);
+  if (!task) return false;
+  try {
+    return hostTaskProjectEnvSpec(task) !== null && currentTaskGatewayRegistration(taskId) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Persist the extended spec, then ALWAYS re-point the live resolver at the
+ * persisted spec, so a repeat repairs a resolver a crash left behind. Throws
+ * when the environment can't take it; Activate then answers `incomplete`.
+ */
+function installProjectEnv(
+  taskId: string,
+  runEpoch: number,
+  project: TaskCommandProject,
+  previewEnv: Record<string, string>,
+): void {
+  const task = getHostTask(taskId);
+  if (!task) throw new Error(`no such task: ${taskId}`);
+  const spec = hostTaskProjectEnvSpec(task);
+  if (spec === null) throw new Error("this task has no persisted env spec to extend");
+  const registration = currentTaskGatewayRegistration(taskId);
+  if (!registration) throw new Error("this task has no live env gateway");
+  const next = specWithProject(spec, project, previewEnv);
+  if (next !== spec) upsertHostTask(taskId, { projectEnvSpec: JSON.stringify(next) });
+  forgetTaskEnvSnapshot(taskId);
+  if (!setTaskGatewayEnvResolver(taskId, registration.generation, taskEnvResolver(taskId, next, runEpoch))) {
+    throw new Error("the task's env gateway changed while the project was installed");
+  }
+}
+
+let singleton: TaskProjectOps | null = null;
+
+export function taskProjectOps(): TaskProjectOps {
+  singleton ??= new TaskProjectOps({
+    journal: new TaskProjectJournalStore(taskUaiDir),
+    environment: async (taskId) => {
+      const task = getHostTask(taskId);
+      if (!task || task.statusMirror !== "running") return null;
+      return reconstructPersistedTaskEnvironment(task);
+    },
+    runIsCurrent,
+    inLifecycleSlot: (taskId, fn) => getOrchestrator().runTaskLifecycle(taskId, fn),
+    credentials: () => (credentialsMode() === "active" ? "cloud" : "own"),
+    installedGrant: (taskId, runEpoch) => {
+      const composer = activeCloudCredentials();
+      if (!composer) return null;
+      const view = composer.registry.currentView({ taskId, runEpoch });
+      return view
+        ? { runEpoch, manifestRevision: view.manifestRevision, manifestDigest: view.manifestDigest }
+        : null;
+    },
+    envServes: (taskId, runEpoch, projectId) => {
+      const composer = activeCloudCredentials();
+      // The runner's own store serves every project it holds values for.
+      if (!composer) return true;
+      const view = composer.registry.currentView({ taskId, runEpoch });
+      if (!view || !view.projectIds.includes(projectId)) return false;
+      return composer.envSnapshot({ taskId, runEpoch }, view.projectIds) !== null;
+    },
+    liveProjectsSupported,
+    captureEnvSchema: (taskId, projectId, git) => captureTaskEnvSchemaFromClone(taskId, projectId, git),
+    storedEnvSchema: (taskId, projectId) => taskEnvSchemaObservation(taskId, projectId),
+    servedProjectIds: (taskId, runEpoch) => {
+      const composer = activeCloudCredentials();
+      if (!composer) return null;
+      const view = composer.registry.currentView({ taskId, runEpoch });
+      if (!view) return null;
+      return composer.envSnapshot({ taskId, runEpoch }, view.projectIds) !== null ? [...view.projectIds] : null;
+    },
+    installProjectEnv,
+  });
+  return singleton;
+}