@runuai/host 0.9.150 → 0.9.151

package/lib/token-broker-ssm.ts

@@ -8,14 +8,23 @@
  */
 
 import {
-  DeleteParameterCommand,
   GetParameterCommand,
+  GetParameterHistoryCommand,
   GetParametersByPathCommand,
+  ListTagsForResourceCommand,
   PutParameterCommand,
   SSMClient,
 } from "@aws-sdk/client-ssm";
 
+import {
+  BROKER_PARAMETER_ROOT,
+  idPathSegment,
+  legacyAdoptedRoot,
+  legacyEngineParameterRoot,
+} from "../src/cloud-credentials";
 import type { BrokerCredential, BrokerStorage } from "./token-broker";
+import type { AdoptionStore } from "./token-broker-adopt";
+import type { RevisionStore, StoredParameter } from "./token-broker-revision";
 import { refreshMetaFrom, type CredentialFiles, type RefreshMeta } from "./token-lanes/types";
 
 export interface SsmBrokerStorageOptions {
@@ -30,7 +39,7 @@ interface StoredValue {
   version: number | undefined;
 }
 
-/** `/uai/orgs/<o>/engines/<kind>/<id>` and `/uai/hosts/<h>/engines/<kind>/<id>`. */
+/** `<prefix>/orgs/<o>/engines/<kind>/<id>` and the corresponding host path. */
 export function engineParameterHeader(
   name: string,
   prefix: string,
@@ -53,6 +62,10 @@ export class SsmBrokerStorage implements BrokerStorage {
   }
 
   async list(): Promise<BrokerCredential[]> {
+    // ADR-154, owner answer 3: an adopted account has one refresher, the
+    // cloud's scheduler, never this scan. Markers that cannot be listed stop
+    // the run rather than risk a second refresher.
+    const adopted = await adoptedLegacyNames(this.client, this.opts.prefix);
     const out: BrokerCredential[] = [];
     for (const path of [`${this.opts.prefix}/orgs`, `${this.opts.prefix}/hosts`]) {
       let nextToken: string | undefined;
@@ -67,6 +80,7 @@ export class SsmBrokerStorage implements BrokerStorage {
         );
         for (const p of page.Parameters ?? []) {
           if (!p.Name || typeof p.Value !== "string") continue;
+          if (adopted.has(p.Name)) continue;
           const header = engineParameterHeader(p.Name, this.opts.prefix);
           if (!header) continue;
           let raw: unknown;
@@ -123,12 +137,132 @@ export class SsmBrokerStorage implements BrokerStorage {
 // ---------------------------------------------------------------------------
 // Mutual exclusion between runs. Reserved concurrency 1 is the first line
 // (deploy-aws.sh sets it when the account's limit allows); this lock is the
-// one that always holds: a `PutParameter` WITHOUT `Overwrite` is atomic, so
-// two runs can never both create `<prefix>/locks/token-broker`. A holder
-// that died keeps the lock at most LOCK_STALE_MS; a later run takes it over.
+// one that always holds. A lock is one parameter that is never deleted: AWS
+// asks for 30 seconds between deleting a parameter and creating one of the
+// same name (DeleteParameter), and adoptions take the scan lock one after
+// another. Free, it holds RELEASED_LOCK; held, its holder's
+// `<time>:<nonce>`. A holder that died keeps it at most LOCK_STALE_MS; a
+// later run takes it over.
 // ---------------------------------------------------------------------------
 
 export const LOCK_STALE_MS = 5 * 60_000;
+/** A holder frees the lock only this far inside the stale window: past it,
+ *  a run that found the lock stale may hold it now. The broker's 120-second
+ *  Lambda timeout (deploy-aws.sh) keeps every holder well inside. */
+const LOCK_RELEASE_MARGIN_MS = 60_000;
+/** A free lock: time zero, which every reader takes for stale (the build
+ *  before this one too, which deleted the parameter instead). */
+export const RELEASED_LOCK = "0:released";
+
+interface LockToken {
+  heldAt: number;
+  /** The SSM version this claimant had to create. Null for the previous
+   *  build's `<time>:<nonce>` tokens and recovery fences, which stay
+   *  conservatively held until released or stale. */
+  expectedVersion: number | null;
+}
+
+function lockToken(value: string | undefined): LockToken | null {
+  if (typeof value !== "string") return null;
+  const parts = value.split(":");
+  const [heldAtText, expectedText] = parts;
+  const heldAt = Number(heldAtText);
+  if (!Number.isSafeInteger(heldAt) || heldAt <= 0) return null;
+  const expectedVersion = Number(expectedText);
+  return {
+    heldAt,
+    expectedVersion:
+      parts.length === 3 && Number.isSafeInteger(expectedVersion) && expectedVersion > 0
+        ? expectedVersion
+        : null,
+  };
+}
+
+/** A contender can land after the elected holder has already released. Its
+ * token is not a lock (its returned SSM version missed the version it named),
+ * but it may also have overwritten a newer holder that is still working.
+ * Replay every intervening version: an elected token opens a hold, RELEASED
+ * closes it, and a losing token changes neither. Only a complete chain ending
+ * with no open hold proves that the current false token is free. */
+async function holderBeforeFalseToken(
+  client: SSMClient,
+  name: string,
+  expectedVersion: number,
+  currentVersion: number,
+): Promise<LockToken | null | undefined> {
+  let nextToken: string | undefined;
+  const history = new Map<number, string>();
+  try {
+    do {
+      const page = await client.send(
+        new GetParameterHistoryCommand({
+          Name: name,
+          WithDecryption: false,
+          MaxResults: 50,
+          NextToken: nextToken,
+        }),
+      );
+      for (const item of page.Parameters ?? []) {
+        if (
+          item.Version !== undefined &&
+          item.Version >= expectedVersion &&
+          item.Version < currentVersion &&
+          item.Value !== undefined
+        ) {
+          history.set(item.Version, item.Value);
+        }
+      }
+      nextToken = page.NextToken;
+    } while (nextToken);
+  } catch {
+    // Missing IAM or a transient history read fails closed. The false token
+    // becomes stale normally; it must never be mistaken for a free live lock.
+  }
+  let holder: LockToken | null = null;
+  for (let version = expectedVersion; version < currentVersion; version += 1) {
+    const value = history.get(version);
+    // A missing/expired history entry cannot prove the holder is gone.
+    if (value === undefined) return undefined;
+    if (value === RELEASED_LOCK) {
+      holder = null;
+      continue;
+    }
+    const claim = lockToken(value);
+    // The previous build's two-field token won its own election; for a new
+    // token, only the exact SSM version it named did. Losing writes do not
+    // erase an already-open hold.
+    if (claim && (claim.expectedVersion === null || claim.expectedVersion === version)) {
+      holder = claim;
+    }
+  }
+  return holder;
+}
+
+function lockWriteConflict(error: unknown): boolean {
+  const name = (error as { name?: string }).name;
+  return name === "ParameterAlreadyExists" || name === "TooManyUpdates";
+}
+
+/** History can age out (SSM retains 100 versions) or be temporarily
+ * unavailable. Replace an unprovable false token with a fresh fence and admit
+ * nobody for one stale window. Any hidden holder predates this write and is
+ * therefore stale when the fence is; a normal holder release may free it
+ * sooner. This is deliberately not an elected holder and never returns a
+ * release callback. */
+async function installRecoveryFence(
+  client: SSMClient,
+  name: string,
+  now: () => number,
+): Promise<void> {
+  const token = `${now()}:recovery:${Math.random().toString(36).slice(2)}`;
+  try {
+    await client.send(
+      new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: true }),
+    );
+  } catch (error) {
+    if (!lockWriteConflict(error)) throw error;
+  }
+}
 
 export function brokerLockName(prefix: string): string {
   return `${prefix}/locks/token-broker`;
@@ -144,42 +278,248 @@ export interface BrokerLockOptions {
 /** Try to take the lock. Returns a release function, or null when another
  *  run holds a fresh one. */
 export async function acquireBrokerLock(opts: BrokerLockOptions): Promise<(() => Promise<void>) | null> {
-  const name = brokerLockName(opts.prefix);
+  return acquireParameterLock({ ...opts, name: brokerLockName(opts.prefix) });
+}
+
+/** The same lock, at any parameter name. */
+export async function acquireParameterLock(opts: {
+  client: SSMClient;
+  name: string;
+  now?: () => number;
+  staleMs?: number;
+}): Promise<(() => Promise<void>) | null> {
+  const name = opts.name;
   const now = opts.now ?? Date.now;
   const staleMs = opts.staleMs ?? LOCK_STALE_MS;
-  const token = `${now()}:${Math.random().toString(36).slice(2)}`;
-  const tryCreate = async (overwrite: boolean): Promise<boolean> => {
+  let current: { Parameter?: { Value?: string; Version?: number } } | null;
+  try {
+    current = await opts.client.send(new GetParameterCommand({ Name: name }));
+  } catch (err) {
+    if ((err as { name?: string }).name !== "ParameterNotFound") throw err;
+    current = null;
+  }
+  if (current !== null) {
+    const claim = lockToken(current.Parameter?.Value);
+    const currentVersion = current.Parameter?.Version;
+    if (claim) {
+      const isElected =
+        claim.expectedVersion === null ||
+        currentVersion === undefined ||
+        claim.expectedVersion === currentVersion;
+      if (isElected) {
+        if (now() - claim.heldAt < staleMs) return null;
+      } else {
+        // Versions only rise. A token naming a future version is malformed,
+        // not evidence that a previous holder released. Fence recovery rather
+        // than leaving the malformed lineage wedged forever.
+        if (claim.expectedVersion! > currentVersion) {
+          await installRecoveryFence(opts.client, name, now);
+          return null;
+        }
+        // Replay a mismatched token even when that token's own timestamp is
+        // stale: it may have landed late over a much newer, live holder.
+        const holder = await holderBeforeFalseToken(
+          opts.client,
+          name,
+          claim.expectedVersion!,
+          currentVersion,
+        );
+        if (holder === undefined) {
+          await installRecoveryFence(opts.client, name, now);
+          return null;
+        }
+        if (holder !== null && now() - holder.heldAt < staleMs) {
+          return null;
+        }
+      }
+    }
+  }
+  // Timed at the write, so a run that lost the election below leaves a token
+  // no older than ours.
+  const takenAt = now();
+  const read = current?.Parameter?.Version;
+  const expectedVersion = current === null ? 1 : read === undefined ? null : read + 1;
+  if (expectedVersion === null) return null;
+  const token = `${takenAt}:${expectedVersion}:${Math.random().toString(36).slice(2)}`;
+  if (current === null) {
+    // Never taken (or deleted by the build before this one): created once.
     try {
-      await opts.client.send(
-        new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: overwrite }),
-      );
-      return true;
+      await opts.client.send(new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: false }));
     } catch (err) {
-      if (!overwrite && (err as { name?: string }).name === "ParameterAlreadyExists") return false;
+      if (lockWriteConflict(err)) return null;
       throw err;
     }
-  };
-  if (!(await tryCreate(false))) {
-    // Someone holds it. Stale?
-    let heldAt = 0;
+  } else {
+    /**
+     * SSM has no conditional overwrite, but it numbers every write: ours is
+     * the lock only if it is the very next version after the one we read
+     * free or stale. Of runs that read the same version, exactly one gets
+     * the next; the others may leave their tokens in the value after it, but
+     * a token is only written over a lock read free or stale, so none of
+     * them holds it meanwhile.
+     */
+    let written: { Version?: number };
     try {
-      const current = await opts.client.send(new GetParameterCommand({ Name: name }));
-      heldAt = Number(current.Parameter?.Value?.split(":")[0] ?? 0) || 0;
-    } catch {
-      heldAt = 0;
+      written = await opts.client.send(
+        new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: true }),
+      );
+    } catch (error) {
+      if (lockWriteConflict(error)) return null;
+      throw error;
     }
-    if (heldAt && now() - heldAt < staleMs) return null;
-    await tryCreate(true);
+    if (written.Version !== expectedVersion) return null;
   }
   return async () => {
+    // Inside the hold no other run can hold the lock, whatever token a run
+    // that lost the election left in the value: free it. Late in it, a run
+    // that found it stale may hold it already; leave it, stale anyway.
+    if (now() - takenAt >= Math.max(0, staleMs - LOCK_RELEASE_MARGIN_MS)) return;
     try {
-      // Only release our own token: a takeover after a stall must not be
-      // undone by the stalled run finishing late.
-      const current = await opts.client.send(new GetParameterCommand({ Name: name }));
-      if (current.Parameter?.Value !== token) return;
-      await opts.client.send(new DeleteParameterCommand({ Name: name }));
+      await opts.client.send(
+        new PutParameterCommand({ Name: name, Value: RELEASED_LOCK, Type: "String", Overwrite: true }),
+      );
     } catch {
       /* the stale window covers a failed release */
     }
   };
 }
+
+// ---------------------------------------------------------------------------
+// ADR-154 §7: one named revision, for the exact-name entry point
+// ---------------------------------------------------------------------------
+
+/** One credential's lock: one invoke at a time per credential, whichever
+ *  revision it names, since an invoke the cloud gave up on may still run. */
+export function revisionLockName(credentialId: string): string {
+  return `${BROKER_PARAMETER_ROOT}/locks/${idPathSegment(credentialId)}`;
+}
+
+export class SsmRevisionStore implements RevisionStore {
+  constructor(
+    private readonly opts: { client: SSMClient; kmsKeyId: string; now?: () => number },
+  ) {}
+
+  async get(name: string): Promise<StoredParameter | null> {
+    try {
+      const out = await this.opts.client.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+      const parameter = out.Parameter;
+      if (parameter?.Value === undefined || parameter.Version === undefined) return null;
+      return { value: parameter.Value, version: parameter.Version };
+    } catch (err) {
+      if ((err as { name?: string }).name === "ParameterNotFound") return null;
+      throw err;
+    }
+  }
+
+  async overwrite(name: string, value: string): Promise<number> {
+    const out = await this.opts.client.send(
+      new PutParameterCommand({
+        Name: name,
+        Value: value,
+        Type: "SecureString",
+        KeyId: this.opts.kmsKeyId,
+        Overwrite: true,
+      }),
+    );
+    if (out.Version === undefined) throw new Error("PutParameter returned no version");
+    return out.Version;
+  }
+
+  lock(credentialId: string): Promise<(() => Promise<void>) | null> {
+    return acquireParameterLock({
+      client: this.opts.client,
+      name: revisionLockName(credentialId),
+      now: this.opts.now,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154, owner answer 3: adoption of today's workspace AI accounts
+// ---------------------------------------------------------------------------
+
+async function parametersUnder(
+  client: SSMClient,
+  path: string,
+  decrypt: boolean,
+): Promise<Array<{ name: string; value: string }>> {
+  const out: Array<{ name: string; value: string }> = [];
+  let nextToken: string | undefined;
+  do {
+    const page = await client.send(
+      new GetParametersByPathCommand({ Path: path, Recursive: true, WithDecryption: decrypt, NextToken: nextToken }),
+    );
+    for (const p of page.Parameters ?? []) {
+      if (p.Name && typeof p.Value === "string") out.push({ name: p.Name, value: p.Value });
+    }
+    nextToken = page.NextToken;
+  } while (nextToken);
+  return out;
+}
+
+/** The legacy parameter names (under `prefix`) an adoption marker names. */
+export async function adoptedLegacyNames(client: SSMClient, prefix: string): Promise<Set<string>> {
+  const names = new Set<string>();
+  const adoptedRoot = legacyAdoptedRoot(prefix);
+  for (const marker of await parametersUnder(client, `${adoptedRoot}/orgs`, false)) {
+    names.add(`${prefix}${marker.name.slice(adoptedRoot.length)}`);
+  }
+  return names;
+}
+
+export class SsmAdoptionStore extends SsmRevisionStore implements AdoptionStore {
+  constructor(
+    private readonly adoption: { client: SSMClient; kmsKeyId: string; prefix: string; now?: () => number },
+  ) {
+    super(adoption);
+  }
+
+  get legacyPrefix(): string {
+    return this.adoption.prefix;
+  }
+
+  async create(name: string, value: string, tags: Record<string, string>): Promise<"created" | "matched"> {
+    const entries = Object.entries(tags);
+    const marker = name.startsWith(`${legacyAdoptedRoot(this.adoption.prefix)}/`);
+    try {
+      await this.adoption.client.send(
+        new PutParameterCommand({
+          Name: name,
+          Value: value,
+          // A marker names ids only; every part is a secret.
+          Type: marker ? "String" : "SecureString",
+          ...(marker ? {} : { KeyId: this.adoption.kmsKeyId }),
+          Tier: marker ? "Standard" : "Advanced",
+          Overwrite: false,
+          Tags: entries.map(([Key, Value]) => ({ Key, Value })),
+        }),
+      );
+      return "created";
+    } catch (error) {
+      if ((error as { name?: string }).name !== "ParameterAlreadyExists") throw error;
+    }
+    // Exists: this create's retry only when its identity tags all match.
+    const listed = await this.adoption.client.send(
+      new ListTagsForResourceCommand({ ResourceType: "Parameter", ResourceId: name }),
+    );
+    const observed = new Map((listed.TagList ?? []).map((tag) => [tag.Key, tag.Value]));
+    for (const [key, expected] of entries) {
+      const actual = observed.get(key);
+      if (actual === undefined) throw new Error(`${name} exists and its tags are not visible yet`);
+      if (actual !== expected) throw new Error(`${name} exists as another credential's`);
+    }
+    return "matched";
+  }
+
+  listLegacy(): Promise<Array<{ name: string; value: string }>> {
+    return parametersUnder(this.adoption.client, legacyEngineParameterRoot(this.adoption.prefix), true);
+  }
+
+  listMarkers(): Promise<Array<{ name: string; value: string }>> {
+    return parametersUnder(this.adoption.client, `${legacyAdoptedRoot(this.adoption.prefix)}/orgs`, false);
+  }
+
+  scanLock(): Promise<(() => Promise<void>) | null> {
+    return acquireBrokerLock({ client: this.adoption.client, prefix: this.adoption.prefix, now: this.adoption.now });
+  }
+}

package/lib/token-lanes/openai-oauth.ts

@@ -19,6 +19,7 @@ import {
   type RefreshOutcome,
   type TokenLane,
 } from "./types";
+import { brokerErrorKind, CREDENTIAL_LANE_SCHEDULES } from "../../src/cloud-credentials";
 
 export const OPENAI_TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
 export const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
@@ -38,7 +39,8 @@ function tokensOf(files: CredentialFiles): {
 export const openaiOAuthLane: TokenLane = {
   id: "openai-oauth",
   endpoints: [OPENAI_TOKEN_ENDPOINT],
-  schedule: { leadMs: 2 * DAY_MS },
+  // ADR-154 §7: the cloud names a revision on the same schedule.
+  schedule: CREDENTIAL_LANE_SCHEDULES["openai-oauth"]!,
   reactiveSignals: [
     /refresh token was revoked/i,
     /refresh_token_reused/i,
@@ -81,11 +83,13 @@ export const openaiOAuthLane: TokenLane = {
         refresh_token: current,
         scope: "openid profile email",
       });
-    } catch (err) {
+    } catch (error) {
       return {
         ok: false,
         terminal: false,
-        reason: `request failed: ${err instanceof Error ? err.message : String(err)}`,
+        // A transport error can quote the request (and therefore the refresh
+        // token) in its message. Only its bounded kind may cross the lane.
+        reason: brokerErrorKind(error),
       };
     }
     if (res.status < 200 || res.status >= 300) {

package/lib/token-lanes/xai-oauth.ts

@@ -25,6 +25,7 @@ import {
   type RefreshOutcome,
   type TokenLane,
 } from "./types";
+import { brokerErrorKind, CREDENTIAL_LANE_SCHEDULES } from "../../src/cloud-credentials";
 
 export const XAI_ISSUER = "https://auth.x.ai";
 export const XAI_TOKEN_ENDPOINT = `${XAI_ISSUER}/oauth2/token`;
@@ -60,7 +61,8 @@ export const xaiOAuthLane: TokenLane = {
   // Observed 2026-09-09: the token lives SIX hours (create_time → expires_at).
   // Refresh with three hours left — the hourly cycle then renews it at about
   // four hours of age — and every four hours when expiry cannot be read.
-  schedule: { leadMs: 3 * HOUR_MS, everyMs: 4 * HOUR_MS },
+  // ADR-154 §7: the cloud names a revision on the same schedule.
+  schedule: CREDENTIAL_LANE_SCHEDULES["xai-oauth"]!,
   reactiveSignals: [/invalid_grant/i, /token (?:has )?expired/i, /log ?in again/i, /unauthorized/i],
 
   matches(header: CredentialHeader, files: CredentialFiles): boolean {
@@ -117,11 +119,13 @@ export const xaiOAuthLane: TokenLane = {
           refresh_token: current,
           client_id: clientId,
         });
-      } catch (err) {
+      } catch (error) {
         return {
           ok: false,
           terminal: false,
-          reason: `request failed: ${err instanceof Error ? err.message : String(err)}`,
+          // A transport error can quote the request (and therefore the refresh
+          // token) in its message. Only its bounded kind may cross the lane.
+          reason: brokerErrorKind(error),
         };
       }
       if (res.status < 200 || res.status >= 300) {

package/lib/transcript.ts

@@ -9,12 +9,12 @@
  * instructions) only — no tool-call execution traces.
  */
 
-import { appendFileSync, mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { mkdirSync } from "node:fs";
 
 import { taskWorkspaceDir } from "./env";
 import { rewriteAttachmentRefs } from "./orchestrator";
 import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { appendContainedFileSync, makeContainedDirectoriesSync } from "./task-environment/workspace-files";
 import type { TranscriptTarget } from "../src/protocol";
 
 /** Container path agents are pointed at. */
@@ -43,10 +43,14 @@ export function appendTranscript(
 ): void {
   const entry = transcriptEntry(author, text);
   if (entry === null) return;
-  const dir = resolve(taskWorkspaceDir(taskId), ".uai");
-  mkdirSync(dir, { recursive: true });
+  // Into the task's own .uai, never through a link the task put there
+  // (#cb3j0z). The workspace root is the runner's own path; .uai, directly
+  // below it, is made if gone without following a link.
+  const workspace = taskWorkspaceDir(taskId);
+  mkdirSync(workspace, { recursive: true });
+  makeContainedDirectoriesSync(workspace, [".uai"]);
   for (const target of new Set(targets)) {
-    appendFileSync(resolve(dir, TARGET_FILENAME[target]), entry);
+    appendContainedFileSync(workspace, [".uai", TARGET_FILENAME[target]], Buffer.from(entry));
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.150",
+  "version": "0.9.151",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",
@@ -57,6 +57,10 @@
       "types": "./src/protocol.ts",
       "default": "./src/protocol.ts"
     },
+    "./cloud-credentials": {
+      "types": "./src/cloud-credentials.ts",
+      "default": "./src/cloud-credentials.ts"
+    },
     "./project-env-policy": {
       "types": "./src/project-env-policy.ts",
       "default": "./src/project-env-policy.ts"
@@ -78,6 +82,7 @@
     "uai-host": "tsx src/cli.ts"
   },
   "dependencies": {
+    "@aws-sdk/client-ssm": "3.899.0",
     "@sentry/node": "^10.66.0",
     "better-sqlite3": "12.11.1",
     "dotenv": "^16.4.5",
@@ -88,7 +93,6 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@aws-sdk/client-ssm": "3.899.0",
     "@types/node": "^22.9.0",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.59.4",