farai 0.2.8 → 0.2.9

package/dist/cli/index.js

@@ -5707,33 +5707,67 @@ var init_docker_environment = __esm(() => {
 
 // src/agent-container/lifecycle.ts
 import { createHash as createHash3 } from "crypto";
+import { statSync as statSync2 } from "fs";
 import { join as join8, resolve as resolve3 } from "path";
 import { Database as Database2 } from "bun:sqlite";
 
 class DockerContainerLifecycle {
   acquired = new Map;
+  stopFailures = new Set;
+  activeOperations = 0;
   lastReconcileAt = 0;
   disposed = false;
+  suspending = false;
   constructor(runtimeId, runner = runDockerProcess, options = {}) {
     this.runtimeId = runtimeId;
     this.runner = runner;
     this.registry = new ContainerLeaseRegistry(options.registryPath);
     this.idleTtlMs = options.idleTtlMs ?? CONTAINER_IDLE_TTL_MS;
+    this.reconcileTimer = setInterval(() => {
+      if (this.disposed || this.suspending)
+        return;
+      this.reconcile().catch(() => {
+        return;
+      });
+    }, CONTAINER_RECONCILE_INTERVAL_MS);
+    this.reconcileTimer.unref?.();
   }
   async acquire(identity) {
     this.assertOpen();
-    if (Date.now() - this.lastReconcileAt >= 60000)
+    this.beginOperation();
+    try {
+      await this.acquireUnlocked(identity);
+    } finally {
+      this.endOperation();
+    }
+  }
+  async withLease(identity, operation) {
+    this.assertOpen();
+    this.beginOperation();
+    try {
+      await this.acquireUnlocked(identity);
+      this.assertOpen();
+      return await operation();
+    } finally {
+      this.endOperation();
+    }
+  }
+  async acquireUnlocked(identity) {
+    if (Date.now() - this.lastReconcileAt >= CONTAINER_RECONCILE_INTERVAL_MS)
       await this.reconcile();
     else
       await this.reconcilePromise;
+    this.assertOpen();
     this.registry.acquire(identity, this.runtimeId, CONTAINER_LEASE_MS);
     this.acquired.set(identity.containerName, identity);
+    this.stopFailures.delete(identity.containerName);
   }
   release(identity) {
     if (this.disposed)
       return;
     this.registry.release(identity.containerName, this.runtimeId);
     this.acquired.delete(identity.containerName);
+    this.stopFailures.delete(identity.containerName);
   }
   renew() {
     if (this.disposed || this.acquired.size === 0)
@@ -5744,8 +5778,10 @@ class DockerContainerLifecycle {
     this.assertOpen();
     if (this.reconcilePromise)
       return this.reconcilePromise;
-    this.reconcilePromise = this.performReconcile().finally(() => {
-      this.lastReconcileAt = Date.now();
+    this.reconcilePromise = this.performReconcile().then((completed) => {
+      if (completed)
+        this.lastReconcileAt = Date.now();
+    }).finally(() => {
       this.reconcilePromise = undefined;
     });
     return this.reconcilePromise;
@@ -5753,83 +5789,285 @@ class DockerContainerLifecycle {
   async performReconcile() {
     const listed = await listManagedContainers(this.runner);
     if (!listed)
-      return;
+      return false;
     const names = new Set(listed.map((container) => container.containerName));
-    const toStop = new Set;
+    const toStop = new Map;
+    const toRemove = new Map;
     for (const container of listed) {
-      if (this.registry.has(container.containerName))
-        continue;
       this.registry.adopt(container);
-      if (container.state === "running")
-        toStop.add(container.containerName);
+      if (this.workspaceIsOrphaned(container.workspace) && this.registry.claimUnleased(container, this.runtimeId, CONTAINER_LEASE_MS)) {
+        if (containerNeedsStop(container.state))
+          toStop.set(container.containerName, container);
+        else
+          toRemove.set(container.containerName, container);
+      } else if (containerNeedsStop(container.state) && this.registry.claimUnleased(container, this.runtimeId, CONTAINER_LEASE_MS)) {
+        toStop.set(container.containerName, container);
+      }
     }
     this.registry.deleteMissing(names);
-    const abandoned = this.registry.expireLeases();
+    const abandoned = this.registry.expireLeases(this.runtimeId, CONTAINER_LEASE_MS);
     for (const identity of abandoned) {
       const container = listed.find((candidate) => candidate.containerName === identity.containerName);
-      if (container?.state === "running")
-        toStop.add(identity.containerName);
+      if (container && managedContainerIdentityMatches(container, identity)) {
+        if (this.workspaceIsOrphaned(container.workspace))
+          toRemove.set(identity.containerName, identity);
+        else if (containerNeedsStop(container.state))
+          toStop.set(identity.containerName, identity);
+        else
+          toRemove.set(identity.containerName, identity);
+      } else {
+        this.registry.delete(identity.containerName, this.runtimeId);
+      }
     }
-    await Promise.allSettled([...toStop].map((name) => this.runner("docker", ["stop", "-t", "1", name])));
+    await Promise.allSettled([...toStop.values()].map((identity) => this.stopIfOwned(identity)));
     const claimed = this.registry.claimExpiredIdle(this.runtimeId, this.idleTtlMs);
-    await Promise.all(claimed.map(async (identity) => {
-      const result = await this.runner("docker", ["rm", "-f", "-v", identity.containerName]);
+    for (const identity of claimed)
+      toRemove.set(identity.containerName, identity);
+    await Promise.all([...toRemove.values()].map((identity) => this.removeIfOwned(identity)));
+    return true;
+  }
+  workspaceIsOrphaned(workspace) {
+    try {
+      return !statSync2(workspace).isDirectory();
+    } catch {
+      return true;
+    }
+  }
+  async stopIfOwned(identity) {
+    let release = true;
+    try {
+      const inspected = await this.inspectContainer(identity.containerName);
+      if (inspected.error) {
+        release = false;
+        return;
+      }
+      if (!inspected.exists || !managedContainerBelongsTo(inspected.labels, identity)) {
+        this.registry.delete(identity.containerName, this.runtimeId);
+        return;
+      }
+      await this.runner("docker", ["stop", "-t", "1", identity.containerName], {
+        timeoutMs: 1250
+      });
+    } catch {} finally {
+      if (release)
+        this.registry.release(identity.containerName, this.runtimeId);
+    }
+  }
+  async removeIfOwned(identity) {
+    try {
+      const inspected = await this.inspectContainer(identity.containerName);
+      if (inspected.error)
+        return;
+      if (!inspected.exists || !managedContainerBelongsTo(inspected.labels, identity)) {
+        this.registry.delete(identity.containerName, this.runtimeId);
+        return;
+      }
+      const result = await this.runner("docker", ["rm", "-f", "-v", identity.containerName], {
+        timeoutMs: 3000
+      });
       if (result.exitCode === 0 || containerDoesNotExist(result))
         this.registry.delete(identity.containerName, this.runtimeId);
       else
         this.registry.release(identity.containerName, this.runtimeId);
-    }));
+    } catch {
+      this.registry.release(identity.containerName, this.runtimeId);
+    }
   }
   async suspendAll() {
     if (this.disposed)
       return;
+    if (this.suspendPromise)
+      return this.suspendPromise;
+    this.suspending = true;
+    this.suspendPromise = this.suspendUnlocked();
+    return this.suspendPromise;
+  }
+  async suspendUnlocked() {
+    await Promise.all([this.waitForOperations(), ...this.reconcilePromise ? [this.reconcilePromise.catch(() => {
+      return;
+    })] : []]);
     const identities = [...this.acquired.values()];
     await Promise.allSettled(identities.map(async (identity) => {
       if (!this.registry.ownedBy(identity.containerName, this.runtimeId))
         return;
-      const result = await this.runner("docker", ["stop", "-t", "1", identity.containerName]);
-      if (result.exitCode !== 0 && !containerDoesNotExist(result) && !containerAlreadyStopped(result))
-        return;
-      this.registry.release(identity.containerName, this.runtimeId);
-      this.acquired.delete(identity.containerName);
+      try {
+        const inspected = await this.inspectContainer(identity.containerName);
+        if (inspected.error) {
+          this.stopFailures.add(identity.containerName);
+          return;
+        }
+        if (!inspected.exists || !managedContainerBelongsTo(inspected.labels, identity)) {
+          this.registry.delete(identity.containerName, this.runtimeId);
+          this.acquired.delete(identity.containerName);
+          this.stopFailures.delete(identity.containerName);
+          return;
+        }
+        const result = await this.runner("docker", ["stop", "-t", "1", identity.containerName], {
+          timeoutMs: 1250
+        });
+        if (result.exitCode !== 0 && !containerDoesNotExist(result) && !containerAlreadyStopped(result)) {
+          this.stopFailures.add(identity.containerName);
+          return;
+        }
+        this.registry.release(identity.containerName, this.runtimeId);
+        this.acquired.delete(identity.containerName);
+        this.stopFailures.delete(identity.containerName);
+      } catch {
+        this.stopFailures.add(identity.containerName);
+      }
     }));
   }
   async remove(identity) {
     this.assertOpen();
-    this.registry.claim(identity, this.runtimeId, CONTAINER_LEASE_MS);
-    this.acquired.set(identity.containerName, identity);
-    const result = await this.runner("docker", ["rm", "-f", "-v", identity.containerName]);
-    if (result.exitCode === 0 || containerDoesNotExist(result)) {
-      this.registry.delete(identity.containerName, this.runtimeId);
-      this.acquired.delete(identity.containerName);
-      if (result.exitCode !== 0)
+    this.beginOperation();
+    try {
+      this.registry.claim(identity, this.runtimeId, CONTAINER_LEASE_MS);
+      this.acquired.set(identity.containerName, identity);
+      let inspected;
+      try {
+        inspected = await this.inspectContainer(identity.containerName);
+      } catch (error) {
+        this.stopFailures.add(identity.containerName);
         return {
-          ...result,
-          exitCode: 0,
+          exitCode: 1,
+          stdout: "",
+          stderr: error instanceof Error ? error.message : String(error),
+          durationMs: 0,
+          timedOut: false
+        };
+      }
+      if (inspected.error) {
+        this.stopFailures.add(identity.containerName);
+        return inspected.error;
+      }
+      if (inspected.exists && !managedContainerBelongsTo(inspected.labels, identity)) {
+        this.registry.delete(identity.containerName, this.runtimeId);
+        this.acquired.delete(identity.containerName);
+        this.stopFailures.delete(identity.containerName);
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `refusing to remove container ${identity.containerName}: ownership labels do not match this Farai session`,
+          durationMs: 0,
           timedOut: false
         };
+      }
+      const result = await this.runner("docker", ["rm", "-f", "-v", identity.containerName], {
+        timeoutMs: 3000
+      });
+      if (result.exitCode === 0 || containerDoesNotExist(result)) {
+        this.registry.delete(identity.containerName, this.runtimeId);
+        this.acquired.delete(identity.containerName);
+        this.stopFailures.delete(identity.containerName);
+        if (result.exitCode !== 0)
+          return {
+            ...result,
+            exitCode: 0,
+            timedOut: false
+          };
+      } else {
+        this.stopFailures.add(identity.containerName);
+      }
+      return result;
+    } finally {
+      this.endOperation();
     }
-    return result;
   }
   dispose() {
+    if (this.disposePromise)
+      return this.disposePromise;
     if (this.disposed)
       return;
-    for (const identity of this.acquired.values())
-      this.registry.release(identity.containerName, this.runtimeId);
-    this.acquired.clear();
-    this.registry.close();
     this.disposed = true;
+    clearInterval(this.reconcileTimer);
+    const finalize = () => {
+      try {
+        for (const identity of this.acquired.values()) {
+          if (!this.stopFailures.has(identity.containerName))
+            this.registry.release(identity.containerName, this.runtimeId);
+        }
+      } finally {
+        this.acquired.clear();
+        this.stopFailures.clear();
+        this.registry.close();
+      }
+    };
+    const waits = [...this.reconcilePromise ? [this.reconcilePromise.catch(() => {
+      return;
+    })] : [], ...this.suspendPromise ? [this.suspendPromise.catch(() => {
+      return;
+    })] : [], this.waitForOperations()];
+    if (!this.reconcilePromise && !this.suspendPromise && this.activeOperations === 0) {
+      finalize();
+      return;
+    }
+    this.disposePromise = Promise.all(waits).then(finalize);
+    return this.disposePromise;
+  }
+  beginOperation() {
+    if (this.suspending)
+      throw new Error("container lifecycle is closing");
+    this.activeOperations += 1;
+  }
+  endOperation() {
+    this.activeOperations -= 1;
+    if (this.activeOperations === 0) {
+      this.resolveOperationDrain?.();
+      this.resolveOperationDrain = undefined;
+      this.operationDrain = undefined;
+    }
+  }
+  waitForOperations() {
+    if (this.activeOperations === 0)
+      return Promise.resolve();
+    if (!this.operationDrain) {
+      this.operationDrain = new Promise((resolve4) => {
+        this.resolveOperationDrain = resolve4;
+      });
+    }
+    return this.operationDrain;
+  }
+  async inspectContainer(containerName) {
+    const result = await this.runner("docker", ["inspect", "-f", "{{json .Config.Labels}}", containerName]);
+    if (result.exitCode !== 0) {
+      if (containerDoesNotExist(result))
+        return {
+          exists: false
+        };
+      return {
+        exists: true,
+        error: result
+      };
+    }
+    try {
+      const labels = JSON.parse(result.stdout.trim());
+      return {
+        exists: true,
+        ...labels ? {
+          labels
+        } : {}
+      };
+    } catch {
+      return {
+        exists: true
+      };
+    }
   }
   assertOpen() {
     if (this.disposed)
       throw new Error("container lifecycle is closed");
+    if (this.suspending)
+      throw new Error("container lifecycle is closing");
   }
 }
 function managedContainerLabels(identity) {
   return ["--label", `${FARAI_MANAGED_LABEL}=true`, "--label", `${FARAI_CONTAINER_KIND_LABEL}=${FARAI_INTERACTIVE_CONTAINER_KIND}`, "--label", `${FARAI_ROOT_SESSION_LABEL}=${identity.rootSessionId}`, "--label", `${FARAI_WORKSPACE_LABEL}=${encodeWorkspace(identity.workspace)}`, "--label", `${FARAI_WORKSPACE_HASH_LABEL}=${workspaceHash(identity.workspace)}`, "--label", `${FARAI_IMAGE_CONTRACT_LABEL}=${identity.imageContract}`];
 }
 function managedContainerLabelsMatch(labels, identity) {
-  return labels?.[FARAI_MANAGED_LABEL] === "true" && labels[FARAI_CONTAINER_KIND_LABEL] === FARAI_INTERACTIVE_CONTAINER_KIND && labels[FARAI_ROOT_SESSION_LABEL] === identity.rootSessionId && labels[FARAI_WORKSPACE_LABEL] === encodeWorkspace(identity.workspace) && labels[FARAI_WORKSPACE_HASH_LABEL] === workspaceHash(identity.workspace) && labels[FARAI_IMAGE_CONTRACT_LABEL] === identity.imageContract;
+  return managedContainerBelongsTo(labels, identity) && labels?.[FARAI_IMAGE_CONTRACT_LABEL] === identity.imageContract;
+}
+function managedContainerBelongsTo(labels, identity) {
+  return labels?.[FARAI_MANAGED_LABEL] === "true" && labels[FARAI_CONTAINER_KIND_LABEL] === FARAI_INTERACTIVE_CONTAINER_KIND && labels[FARAI_ROOT_SESSION_LABEL] === identity.rootSessionId && labels[FARAI_WORKSPACE_LABEL] === encodeWorkspace(identity.workspace) && (!labels[FARAI_WORKSPACE_HASH_LABEL] || labels[FARAI_WORKSPACE_HASH_LABEL] === workspaceHash(identity.workspace));
 }
 function workspaceHash(workspace) {
   return createHash3("sha256").update(resolve3(workspace)).digest("hex");
@@ -5906,22 +6144,34 @@ class ContainerLeaseRegistry {
       $now: now
     });
   }
-  expireLeases() {
+  expireLeases(runtimeId, leaseMs) {
     const now = new Date().toISOString();
     const rows = this.db.query(`select * from container_leases
-      where lease_owner is not null and lease_expires_at is not null and lease_expires_at <= $now`).all({
-      $now: now
+      where lease_owner is not null and lease_owner != $owner and lease_expires_at is not null and lease_expires_at <= $now`).all({
+      $now: now,
+      $owner: runtimeId
     });
-    const update = this.db.query(`update container_leases set lease_owner = null, lease_expires_at = null,
-      idle_since = coalesce(idle_since, $now), last_used_at = $now where container_name = $name`);
+    const expires = new Date(Date.now() + leaseMs).toISOString();
+    const update = this.db.query(`update container_leases set lease_owner = $owner, lease_expires_at = $expires,
+      idle_since = coalesce(idle_since, $idle), last_used_at = $now
+      where container_name = $name and lease_owner = $previousOwner and lease_expires_at = $previousExpires`);
+    const claimed = [];
     this.db.transaction(() => {
-      for (const row of rows)
-        update.run({
+      for (const row of rows) {
+        const result = update.run({
           $name: row.container_name,
-          $now: row.lease_expires_at ?? now
+          $previousOwner: row.lease_owner,
+          $previousExpires: row.lease_expires_at,
+          $owner: runtimeId,
+          $expires: expires,
+          $idle: row.lease_expires_at ?? now,
+          $now: now
         });
-    })();
-    return rows.map(identityFromRow);
+        if (result.changes === 1)
+          claimed.push(row);
+      }
+    }).immediate();
+    return claimed.map(identityFromRow);
   }
   claimExpiredIdle(runtimeId, idleTtlMs) {
     const cutoff = new Date(Date.now() - Math.max(0, idleTtlMs)).toISOString();
@@ -5931,14 +6181,16 @@ class ContainerLeaseRegistry {
     });
     const expires = new Date(Date.now() + CONTAINER_LEASE_MS).toISOString();
     const claim = this.db.query(`update container_leases set lease_owner = $owner, lease_expires_at = $expires
-      where container_name = $name and lease_owner is null`);
+      where container_name = $name and lease_owner is null and lease_expires_at is null
+        and idle_since = $idle`);
     const claimed = [];
     this.db.transaction(() => {
       for (const row of rows) {
         const result = claim.run({
           $name: row.container_name,
           $owner: runtimeId,
-          $expires: expires
+          $expires: expires,
+          $idle: row.idle_since
         });
         if (result.changes === 1)
           claimed.push(row);
@@ -5948,9 +6200,22 @@ class ContainerLeaseRegistry {
   }
   adopt(identity) {
     const now = new Date().toISOString();
-    this.db.query(`insert or ignore into container_leases
+    this.db.query(`insert into container_leases
       (container_name, root_session_id, workspace, image_contract, lease_owner, lease_expires_at, idle_since, last_used_at)
-      values ($name, $root, $workspace, $contract, null, null, $now, $now)`).run({
+      values ($name, $root, $workspace, $contract, null, null, $now, $now)
+      on conflict(container_name) do update set
+        root_session_id = excluded.root_session_id,
+        workspace = excluded.workspace,
+        image_contract = excluded.image_contract,
+        idle_since = case when container_leases.root_session_id <> excluded.root_session_id
+          or container_leases.workspace <> excluded.workspace
+          or container_leases.image_contract <> excluded.image_contract
+          then excluded.idle_since else coalesce(container_leases.idle_since, excluded.idle_since) end,
+        last_used_at = case when container_leases.root_session_id <> excluded.root_session_id
+          or container_leases.workspace <> excluded.workspace
+          or container_leases.image_contract <> excluded.image_contract
+          then excluded.last_used_at else container_leases.last_used_at end
+      where container_leases.lease_owner is null`).run({
       $name: identity.containerName,
       $root: identity.rootSessionId,
       $workspace: resolve3(identity.workspace),
@@ -5958,6 +6223,20 @@ class ContainerLeaseRegistry {
       $now: now
     });
   }
+  claimUnleased(identity, runtimeId, leaseMs) {
+    const expires = new Date(Date.now() + leaseMs).toISOString();
+    const result = this.db.query(`update container_leases set lease_owner = $owner, lease_expires_at = $expires
+      where container_name = $name and root_session_id = $root and workspace = $workspace
+        and image_contract = $contract and lease_owner is null and lease_expires_at is null`).run({
+      $name: identity.containerName,
+      $root: identity.rootSessionId,
+      $workspace: resolve3(identity.workspace),
+      $contract: identity.imageContract,
+      $owner: runtimeId,
+      $expires: expires
+    });
+    return result.changes === 1;
+  }
   has(containerName) {
     return Boolean(this.row(containerName));
   }
@@ -6012,15 +6291,22 @@ class ContainerLeaseRegistry {
   }
 }
 async function listManagedContainers(runner) {
-  const format = `{{.Names}}	{{.State}}	{{.Label "${FARAI_ROOT_SESSION_LABEL}"}}	{{.Label "${FARAI_WORKSPACE_LABEL}"}}	{{.Label "${FARAI_IMAGE_CONTRACT_LABEL}"}}`;
-  const result = await runner("docker", ["ps", "-a", "--filter", `label=${FARAI_MANAGED_LABEL}=true`, "--filter", `label=${FARAI_CONTAINER_KIND_LABEL}=${FARAI_INTERACTIVE_CONTAINER_KIND}`, "--format", format]);
+  const format = `{{.Names}}	{{.State}}	{{.Label "${FARAI_ROOT_SESSION_LABEL}"}}	{{.Label "${FARAI_WORKSPACE_LABEL}"}}	{{.Label "${FARAI_WORKSPACE_HASH_LABEL}"}}	{{.Label "${FARAI_IMAGE_CONTRACT_LABEL}"}}`;
+  const result = await runner("docker", ["ps", "-a", "--filter", `label=${FARAI_MANAGED_LABEL}=true`, "--filter", `label=${FARAI_CONTAINER_KIND_LABEL}=${FARAI_INTERACTIVE_CONTAINER_KIND}`, "--format", format], {
+    timeoutMs: 3000
+  });
   if (result.exitCode !== 0)
     return;
   return result.stdout.split(`
 `).flatMap((line) => {
-    const [containerName, state, rootSessionId, encodedWorkspace, imageContract] = line.trim().split("\t");
+    const fields = line.trim().split("\t");
+    const [containerName, state, rootSessionId, encodedWorkspace] = fields;
+    const encodedWorkspaceHash = fields.length >= 6 ? fields[4] : "";
+    const imageContract = fields.length >= 6 ? fields[5] : fields[4];
     const workspace = encodedWorkspace ? decodeWorkspace(encodedWorkspace) : undefined;
-    if (!containerName || !state || !rootSessionId || !workspace || !imageContract)
+    if (!containerName || !containerName.startsWith(FARAI_CONTAINER_NAME_PREFIX) || !state || !rootSessionId || !workspace || !imageContract)
+      return [];
+    if (encodedWorkspaceHash && encodedWorkspaceHash !== workspaceHash(workspace))
       return [];
     return [{
       containerName,
@@ -6040,20 +6326,29 @@ function identityFromRow(row) {
   };
 }
 function containerDoesNotExist(result) {
-  return /no such container/i.test(`${result.stdout}
+  return /no such (container|object)/i.test(`${result.stdout}
 ${result.stderr}`);
 }
 function containerAlreadyStopped(result) {
   return /is not running|already stopped/i.test(`${result.stdout}
 ${result.stderr}`);
 }
-async function runDockerProcess(command, args, timeoutMs = 15000) {
+function containerNeedsStop(state) {
+  return ["created", "running", "restarting", "paused"].includes(state.toLowerCase());
+}
+function managedContainerIdentityMatches(left, right) {
+  return left.rootSessionId === right.rootSessionId && resolve3(left.workspace) === resolve3(right.workspace);
+}
+async function runDockerProcess(command, args, options = {}) {
   return await runCapturedProcess(command, args, {
-    timeoutMs,
+    timeoutMs: options.timeoutMs ?? 3000,
+    ...options.signal ? {
+      signal: options.signal
+    } : {},
     env: faraiDockerEnvironment()
   });
 }
-var FARAI_MANAGED_LABEL = "org.farai.managed", FARAI_CONTAINER_KIND_LABEL = "org.farai.kind", FARAI_ROOT_SESSION_LABEL = "org.farai.root-session", FARAI_WORKSPACE_LABEL = "org.farai.workspace", FARAI_WORKSPACE_HASH_LABEL = "org.farai.workspace-hash", FARAI_IMAGE_CONTRACT_LABEL = "org.farai.image-contract", FARAI_INTERACTIVE_CONTAINER_KIND = "interactive", CONTAINER_LEASE_MS = 60000, CONTAINER_IDLE_TTL_MS;
+var FARAI_MANAGED_LABEL = "org.farai.managed", FARAI_CONTAINER_KIND_LABEL = "org.farai.kind", FARAI_ROOT_SESSION_LABEL = "org.farai.root-session", FARAI_WORKSPACE_LABEL = "org.farai.workspace", FARAI_WORKSPACE_HASH_LABEL = "org.farai.workspace-hash", FARAI_IMAGE_CONTRACT_LABEL = "org.farai.image-contract", FARAI_INTERACTIVE_CONTAINER_KIND = "interactive", FARAI_CONTAINER_NAME_PREFIX = "farai-kali-", CONTAINER_LEASE_MS = 60000, CONTAINER_IDLE_TTL_MS, CONTAINER_RECONCILE_INTERVAL_MS = 60000;
 var init_lifecycle = __esm(() => {
   init_config();
   init_captured_process();
@@ -6121,12 +6416,15 @@ class KaliContainerBackend {
   async status() {
     const image = await this.resolveImage();
     const dockerContext = (await this.processRunner("docker", ["context", "show"])).stdout.trim();
-    const inspected = await this.inspectPersistent();
+    const inspectedResult = await this.inspectPersistent();
+    const inspected = inspectedResult.container;
     const persistentExists = Boolean(inspected);
     const persistentRunning = inspected?.state === "running";
     const persistentImageId = inspected?.imageId ?? "";
     const persistentImageCurrent = Boolean(persistentExists && image.id && persistentImageId && imageIdsMatch(image.id, persistentImageId));
     const persistentIdentityCurrent = Boolean(this.identity && managedContainerLabelsMatch(inspected?.labels, this.identity));
+    const persistentManaged = Boolean(this.identity && managedContainerBelongsTo(inspected?.labels, this.identity));
+    const dockerError = image.error ?? inspectedResult.error;
     return {
       image: this.image,
       imageExists: image.exists,
@@ -6150,30 +6448,43 @@ class KaliContainerBackend {
         persistentImageId
       } : {},
       persistentImageCurrent,
-      persistentIdentityCurrent
+      persistentIdentityCurrent,
+      persistentManaged,
+      ...dockerError ? {
+        dockerError
+      } : {}
     };
   }
   async inspectPersistent() {
     const inspected = await this.processRunner("docker", ["inspect", "-f", "{{.State.Status}}\t{{.Image}}\t{{json .Config.Labels}}", this.containerName]);
-    if (inspected.exitCode !== 0)
-      return;
+    if (inspected.exitCode !== 0) {
+      if (containerDoesNotExist2(inspected) || !inspected.stdout.trim() && !inspected.stderr.trim())
+        return {};
+      return {
+        error: dockerFailure(inspected, `unable to inspect persistent Kali container ${this.containerName}`)
+      };
+    }
     const [state = "unknown", imageId = "", labelsJson = ""] = inspected.stdout.trim().split("\t", 3);
     try {
       return {
-        state: state || "unknown",
-        ...imageId ? {
-          imageId
-        } : {},
-        ...labelsJson && labelsJson !== "null" ? {
-          labels: JSON.parse(labelsJson)
-        } : {}
+        container: {
+          state: state || "unknown",
+          ...imageId ? {
+            imageId
+          } : {},
+          ...labelsJson && labelsJson !== "null" ? {
+            labels: JSON.parse(labelsJson)
+          } : {}
+        }
       };
     } catch {
       return {
-        state: state || "unknown",
-        ...imageId ? {
-          imageId
-        } : {}
+        container: {
+          state: state || "unknown",
+          ...imageId ? {
+            imageId
+          } : {}
+        }
       };
     }
   }
@@ -6191,6 +6502,12 @@ class KaliContainerBackend {
         exists: false
       };
     const listed = await this.processRunner("docker", ["image", "ls", repository, "--format", "{{.Repository}}:{{.Tag}} {{.ID}}"]);
+    if (listed.exitCode !== 0) {
+      return {
+        exists: false,
+        error: dockerFailure(listed, `unable to inspect local Docker images for ${this.image}`)
+      };
+    }
     const line = listed.stdout.split(`
 `).map((candidate) => candidate.trim()).find((candidate) => candidate.startsWith(`${repository}:${tag} `));
     if (!line)
@@ -6206,7 +6523,8 @@ class KaliContainerBackend {
     if (inspectById.exitCode !== 0)
       return {
         exists: true,
-        id: id2
+        id: id2,
+        error: dockerFailure(inspectById, `unable to inspect local Docker image ${id2}`)
       };
     const resolved = parseImageInspect(inspectById.stdout);
     return {
@@ -6229,8 +6547,14 @@ class KaliContainerBackend {
     }
   }
   async startPersistentUnlocked() {
+    if (this.identity && this.lifecycle?.withLease) {
+      return await this.lifecycle.withLease(this.identity, () => this.startPersistentBody());
+    }
     if (this.identity && this.lifecycle)
       await this.lifecycle.acquire(this.identity);
+    return await this.startPersistentBody();
+  }
+  async startPersistentBody() {
     try {
       const status = await this.status();
       if (!status.imageExists) {
@@ -6239,7 +6563,28 @@ class KaliContainerBackend {
         return {
           exitCode: 1,
           stdout: "",
-          stderr: `kali image ${this.image} is missing; run \`farai setup --no-kb\``,
+          stderr: status.dockerError ?? `kali image ${this.image} is missing; run \`farai setup --no-kb\``,
+          durationMs: 0,
+          timedOut: false
+        };
+      }
+      if (status.dockerError) {
+        if (this.identity && this.lifecycle)
+          this.lifecycle.release(this.identity);
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: status.dockerError,
+          durationMs: 0,
+          timedOut: false
+        };
+      }
+      if (status.persistentExists && this.identity && !status.persistentManaged) {
+        this.lifecycle?.release(this.identity);
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `refusing to use container ${this.containerName}: ownership labels do not match this Farai session`,
           durationMs: 0,
           timedOut: false
         };
@@ -6276,7 +6621,15 @@ class KaliContainerBackend {
         };
       }
       return await withGlobalContainerStartLock(async () => {
-        await this.processRunner("docker", ["rm", "-f", "-v", this.containerName]);
+        const removed = await this.processRunner("docker", ["rm", "-f", "-v", this.containerName]);
+        if (removed.exitCode !== 0 && !containerDoesNotExist2(removed)) {
+          if (this.identity && this.lifecycle)
+            this.lifecycle.release(this.identity);
+          return {
+            ...removed,
+            stderr: removed.stderr || `could not remove stale Kali container ${this.containerName}`
+          };
+        }
         const worktrees = join9(this.rootWorkspace, ".farai", "worktrees");
         mkdirSync4(worktrees, {
           recursive: true
@@ -6318,6 +6671,11 @@ class KaliContainerBackend {
     };
   }
   async stopPersistent() {
+    const previous = containerStartLocks.get(this.containerName);
+    if (previous)
+      await previous.catch(() => {
+        return;
+      });
     if (this.identity && this.lifecycle)
       return await this.lifecycle.remove(this.identity);
     const started = Date.now();
@@ -6676,6 +7034,11 @@ function parseImageInspect(raw) {
     };
   }
 }
+function dockerFailure(result, fallback) {
+  const detail = `${result.stderr}
+${result.stdout}`.trim().replace(/\s+/g, " ");
+  return detail ? `${fallback}: ${detail.slice(0, 500)}` : fallback;
+}
 function imageIdsMatch(left, right) {
   const normalizedLeft = left.replace(/^sha256:/, "");
   const normalizedRight = right.replace(/^sha256:/, "");
@@ -6691,10 +7054,10 @@ async function runProcess(command, args, timeoutMs = 15000) {
   });
 }
 function containerDoesNotExist2(result) {
-  return /no such container/i.test(`${result.stdout}
+  return /no such (container|object)/i.test(`${result.stdout}
 ${result.stderr}`);
 }
-var CONTAINER_WORKSPACE_MOUNT = "/workspace", CONTAINER_WORKTREES_MOUNT = "/worktrees", kaliSessions, kaliPtySessions, containerStartLocks, globalContainerStartChain, CONTAINER_EXEC_MARKER_DIR = "/tmp/farai-exec", CONTAINER_EXEC_WRAPPER, CONTAINER_EXEC_KILLER, CONTAINER_PREFIX = "farai-kali-", KALI_IMAGE_CONTRACT, DEFAULT_KALI_IMAGE = "farai-kali:latest", KALI_IMAGE_CONTRACT_LABEL = "org.farai.kali.contract";
+var CONTAINER_WORKSPACE_MOUNT = "/workspace", CONTAINER_WORKTREES_MOUNT = "/worktrees", kaliSessions, kaliPtySessions, containerStartLocks, globalContainerStartChain, CONTAINER_EXEC_MARKER_DIR = "/tmp/farai-exec", CONTAINER_EXEC_WRAPPER, CONTAINER_EXEC_KILLER, CONTAINER_PREFIX, KALI_IMAGE_CONTRACT, DEFAULT_KALI_IMAGE = "farai-kali:latest", KALI_IMAGE_CONTRACT_LABEL = "org.farai.kali.contract";
 var init_kali = __esm(() => {
   init_spawn_session();
   init_pty_session();
@@ -6711,6 +7074,7 @@ var init_kali = __esm(() => {
 `);
   CONTAINER_EXEC_KILLER = ["import os, signal, sys, time", "path = sys.argv[1]", "root = None", "marker_deadline = time.monotonic() + 0.25", "while root is None and time.monotonic() < marker_deadline:", "    try:", "        with open(path, encoding='ascii') as handle:", "            root = int(handle.read().strip())", "    except (FileNotFoundError, OSError, ValueError):", "        time.sleep(0.01)", "if root is None:", "    raise SystemExit(0)", "def direct_children(pid):", "    try:", "        with open(f'/proc/{pid}/task/{pid}/children', encoding='ascii') as handle:", "            return [int(value) for value in handle.read().split()]", "    except (FileNotFoundError, OSError, ValueError):", "        return []", "def descendants(pid):", "    found = []", "    pending = direct_children(pid)", "    seen = set()", "    while pending:", "        child = pending.pop()", "        if child in seen:", "            continue", "        seen.add(child)", "        found.append(child)", "        pending.extend(direct_children(child))", "    return found", "def alive(pid):", "    try:", "        os.kill(pid, 0)", "        return True", "    except ProcessLookupError:", "        return False", "    except PermissionError:", "        return True", "targets = descendants(root)", "for pid in [*reversed(targets), root]:", "    try:", "        os.kill(pid, signal.SIGTERM)", "    except (ProcessLookupError, PermissionError):", "        pass", "deadline = time.monotonic() + 1.0", "while time.monotonic() < deadline and any(alive(pid) for pid in [root, *targets]):", "    time.sleep(0.025)", "targets = list(dict.fromkeys([*targets, *descendants(root)]))", "for pid in [*reversed(targets), root]:", "    try:", "        os.kill(pid, signal.SIGKILL)", "    except (ProcessLookupError, PermissionError):", "        pass", "try:", "    os.unlink(path)", "except FileNotFoundError:", "    pass"].join(`
 `);
+  CONTAINER_PREFIX = FARAI_CONTAINER_NAME_PREFIX;
   KALI_IMAGE_CONTRACT = KALI_TOOL_MANIFEST.contract;
 });
 
@@ -7463,8 +7827,8 @@ var init_process_output = __esm(() => {
 
 // src/version.ts
 function resolveFaraiVersion() {
-  if ("0.2.8")
-    return "0.2.8";
+  if ("0.2.9")
+    return "0.2.9";
   try {
     const parsed = JSON.parse(readBoundedFileTextSync(new URL("../package.json", import.meta.url), 1024 * 1024, "package metadata"));
     if (typeof parsed.version === "string" && parsed.version)
@@ -16905,7 +17269,7 @@ var init_patch_apply = __esm(() => {
 });
 
 // src/agent-tools/filesystem/notebook-edit.ts
-import { statSync as statSync2 } from "fs";
+import { statSync as statSync3 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
 function parseNotebook(text2) {
   const value = JSON.parse(text2);
@@ -16922,7 +17286,7 @@ function parseNotebook(text2) {
   return value;
 }
 function writeNotebookAtomically(path, content) {
-  const mode = statSync2(path).mode & 511;
+  const mode = statSync3(path).mode & 511;
   atomicWriteFile(path, content, mode);
 }
 function newCell(cellType, source, includeId) {
@@ -17408,6 +17772,9 @@ function parseActiveContent(value) {
     return;
   if (!validDate(record2.generatedAt) || !validDate(record2.activatedAt))
     return;
+  if (record2.sourceCommit !== undefined && (typeof record2.sourceCommit !== "string" || !SOURCE_COMMIT_PATTERN.test(record2.sourceCommit)))
+    return;
+  const sourceCommit = typeof record2.sourceCommit === "string" ? record2.sourceCommit : undefined;
   if (typeof record2.manifestUrl !== "string" || !record2.manifestUrl)
     return;
   if (typeof record2.knowledge !== "boolean" || typeof record2.skills !== "boolean")
@@ -17417,6 +17784,9 @@ function parseActiveContent(value) {
     schemaVersion: 1,
     version: record2.version,
     generatedAt: record2.generatedAt,
+    ...sourceCommit ? {
+      sourceCommit
+    } : {},
     activatedAt: record2.activatedAt,
     manifestUrl: record2.manifestUrl,
     ...previousVersion ? {
@@ -17429,18 +17799,19 @@ function parseActiveContent(value) {
 function validDate(value) {
   return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
 }
-var POINTER_MAX_BYTES, VERSION_PATTERN;
+var POINTER_MAX_BYTES, VERSION_PATTERN, SOURCE_COMMIT_PATTERN;
 var init_paths2 = __esm(() => {
   init_paths();
   init_private_path();
   init_file_read();
   POINTER_MAX_BYTES = 64 * 1024;
   VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+  SOURCE_COMMIT_PATTERN = /^[a-f0-9]{40}$/;
 });
 
 // src/agent-skills/registry.ts
 import { createHash as createHash5 } from "crypto";
-import { existsSync as existsSync9, readdirSync as readdirSync3, realpathSync as realpathSync2, statSync as statSync3 } from "fs";
+import { existsSync as existsSync9, readdirSync as readdirSync3, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
 import { homedir as homedir4 } from "os";
 import { delimiter, isAbsolute as isAbsolute5, join as join14, relative as relative4, resolve as resolve8, sep as sep2 } from "path";
 function discoverSkills(options = {}) {
@@ -17501,7 +17872,7 @@ function loadSkill(name, options = {}) {
   const canonical = realpathSync2(absolute);
   if (!inside(skill.directory, canonical))
     return;
-  const stats = statSync3(canonical);
+  const stats = statSync4(canonical);
   if (!stats.isFile() || stats.size > MAX_RESOURCE_BYTES)
     return;
   const content = readBoundedFileTextSync(canonical, MAX_RESOURCE_BYTES, "skill resource");
@@ -17533,11 +17904,7 @@ function renderSkillCatalog(workspace, maxChars = 8000) {
 `), maxChars);
 }
 function skillRoots(options) {
-  const roots = [{
-    path: BUILTIN_DIR,
-    source: "builtin",
-    priority: 0
-  }];
+  const roots = [];
   const content = activeContentSkillsDir();
   if (content)
     roots.push({
@@ -17604,10 +17971,6 @@ function scanRoot(root, diagnostics) {
   }
   return skills;
 }
-function resolveBuiltinSkillDir() {
-  const candidates = [join14(import.meta.dir, "library"), join14(import.meta.dir, "..", "..", "src", "agent-skills", "library")];
-  return candidates.find((candidate) => existsSync9(candidate)) ?? candidates[0];
-}
 function parseSkill(file, directory, directoryName, root, diagnostics) {
   let raw;
   try {
@@ -17812,11 +18175,10 @@ function compactText(value, max) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-var BUILTIN_DIR, MAX_SKILL_BYTES, RECOMMENDED_SKILL_BYTES, MAX_RESOURCE_BYTES, MAX_RESOURCES = 256, NAME_PATTERN;
+var MAX_SKILL_BYTES, RECOMMENDED_SKILL_BYTES, MAX_RESOURCE_BYTES, MAX_RESOURCES = 256, NAME_PATTERN;
 var init_registry2 = __esm(() => {
   init_file_read();
   init_paths2();
-  BUILTIN_DIR = resolveBuiltinSkillDir();
   MAX_SKILL_BYTES = 64 * 1024;
   RECOMMENDED_SKILL_BYTES = 20 * 1024;
   MAX_RESOURCE_BYTES = 128 * 1024;
@@ -17951,7 +18313,7 @@ var init_global_config = __esm(() => {
 
 // src/agent-core/context-builder.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync10, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
+import { existsSync as existsSync10, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
 import { isAbsolute as isAbsolute6, join as join15, normalize as normalize2, relative as relative5 } from "path";
 
 class ContextBuilderCache {
@@ -18205,7 +18567,7 @@ function workspaceFileFingerprint(workspace) {
 }
 function statFingerprint(path) {
   try {
-    const stat = statSync4(path);
+    const stat = statSync5(path);
     return `${path}:${stat.mtimeMs}:${stat.size}:${stat.ino}`;
   } catch {
     return `${path}:missing`;
@@ -18219,7 +18581,7 @@ function validWorkspaceFiles(workspace, paths) {
       continue;
     const absolute = join15(workspace, rel);
     try {
-      if (statSync4(absolute).isFile())
+      if (statSync5(absolute).isFile())
         files.push(rel);
     } catch {}
   }
@@ -22905,7 +23267,7 @@ var init_web = __esm(() => {
 });
 
 // src/agent-tools/media/image-view.ts
-import { statSync as statSync5 } from "fs";
+import { statSync as statSync6 } from "fs";
 import { basename as basename3, relative as relative6 } from "path";
 function detectImage(data) {
   if (data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
@@ -22954,7 +23316,7 @@ var init_image_view = __esm(() => {
       assertObject(args, "args");
       const requested = asString(args.path, "path");
       const path = safeExistingWorkspacePath(context.workspace, requested, "read");
-      const stat = statSync5(path);
+      const stat = statSync6(path);
       if (!stat.isFile())
         throw new Error(`not a file: ${requested}`);
       if (stat.size > MAX_IMAGE_BYTES)
@@ -34806,6 +35168,7 @@ class AgentRuntime {
     for (const controller of this.subagentControllers.values())
       controller.abort("runtime shutdown");
     const drain = Promise.allSettled([...[...this.actors.values()].map((actor) => actor.idle()), this.workspaceBindingGate.idle(), this.toolExecutionGate.idle(), this.subagentGate.idle(), this.subagentWorkspaceMutationGate.idle(), ...this.recoveryPromise ? [this.recoveryPromise] : []]);
+    const drainGracePeriod = shutdownGracePeriod(options.gracePeriodMs);
     this.shutdownFinalizationPromise = (async () => {
       const failures = [];
       const attempt = async (label, operation) => {
@@ -34818,7 +35181,11 @@ class AgentRuntime {
         }
       };
       try {
-        await drain;
+        const drained = await waitForShutdownFinalization(drain, drainGracePeriod);
+        if (!drained) {
+          for (const lease of this.activeToolLeases)
+            lease.revoke("runtime shutdown grace period expired");
+        }
         this.activeToolControllers.clear();
         this.activeToolLeases.clear();
         this.subagentControllers.clear();
@@ -34995,6 +35362,10 @@ class AgentRuntime {
       await this.recoveryPromise;
     } catch (error) {
       this.stopRuntimeLease();
+      if (this.shuttingDown)
+        throw new Error("Farai runtime is shutting down", {
+          cause: error
+        });
       throw error;
     } finally {
       this.recoveryPromise = undefined;
@@ -39335,6 +39706,7 @@ function parseContentManifest(value, baseUrl) {
     throw new Error("invalid content version");
   if (typeof record3.generatedAt !== "string" || !Number.isFinite(Date.parse(record3.generatedAt)))
     throw new Error("invalid content generatedAt");
+  const sourceCommit = optionalSourceCommit(record3.sourceCommit);
   const minFaraiVersion = optionalString2(record3.minFaraiVersion, 128, "minFaraiVersion");
   if (minFaraiVersion && !isSemver(minFaraiVersion))
     throw new Error("invalid content minFaraiVersion");
@@ -39345,6 +39717,9 @@ function parseContentManifest(value, baseUrl) {
     schemaVersion: 1,
     contentVersion: record3.contentVersion,
     generatedAt: new Date(record3.generatedAt).toISOString(),
+    ...sourceCommit ? {
+      sourceCommit
+    } : {},
     ...minFaraiVersion ? {
       minFaraiVersion
     } : {},
@@ -39359,6 +39734,13 @@ function parseContentManifest(value, baseUrl) {
     } : {}
   };
 }
+function optionalSourceCommit(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !SOURCE_COMMIT_PATTERN2.test(value))
+    throw new Error("invalid content sourceCommit");
+  return value;
+}
 function artifact(value, baseUrl, label) {
   if (value === undefined)
     return;
@@ -39395,13 +39777,14 @@ function optionalString2(value, maxLength, label) {
     throw new Error(`invalid content ${label}`);
   return value.trim();
 }
-var CONTENT_MANIFEST_SCHEMA_VERSION = 1, CONTENT_MANIFEST_MAX_BYTES, DEFAULT_CONTENT_MANIFEST_URL = "https://github.com/pajarori/farai-data/releases/latest/download/manifest.json", CONTENT_VERSION_PATTERN, SHA256_PATTERN;
+var CONTENT_MANIFEST_SCHEMA_VERSION = 1, CONTENT_MANIFEST_MAX_BYTES, DEFAULT_CONTENT_MANIFEST_URL = "https://github.com/pajarori/farai-data/releases/download/latest/manifest.json", CONTENT_VERSION_PATTERN, SHA256_PATTERN, SOURCE_COMMIT_PATTERN2;
 var init_manifest = __esm(() => {
   init_http_response();
   init_file_read();
   CONTENT_MANIFEST_MAX_BYTES = 256 * 1024;
   CONTENT_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
   SHA256_PATTERN = /^[a-f0-9]{64}$/;
+  SOURCE_COMMIT_PATTERN2 = /^[a-f0-9]{40}$/;
 });
 
 // src/agent-content/updater.ts
@@ -39417,7 +39800,7 @@ __export(exports_updater, {
   CONTENT_MANIFEST_CACHE_TTL_MS: () => CONTENT_MANIFEST_CACHE_TTL_MS
 });
 import { createHash as createHash10, randomUUID as randomUUID4 } from "crypto";
-import { closeSync as closeSync4, existsSync as existsSync18, lstatSync as lstatSync4, mkdirSync as mkdirSync7, openSync as openSync4, readSync as readSync2, readdirSync as readdirSync6, renameSync as renameSync3, rmSync as rmSync3, statSync as statSync6, unlinkSync as unlinkSync6, writeSync } from "fs";
+import { closeSync as closeSync4, existsSync as existsSync18, lstatSync as lstatSync4, mkdirSync as mkdirSync7, openSync as openSync4, readSync as readSync2, readdirSync as readdirSync6, renameSync as renameSync3, rmSync as rmSync3, statSync as statSync7, unlinkSync as unlinkSync6, writeSync } from "fs";
 import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function checkContentUpdate(options = {}) {
@@ -39592,6 +39975,9 @@ async function applyContentUpdate(manifest, manifestUrl, options = {}) {
       generatedAt: manifest.generatedAt,
       activatedAt: new Date().toISOString(),
       manifestUrl,
+      ...manifest.sourceCommit ? {
+        sourceCommit: manifest.sourceCommit
+      } : {},
       ...previous && previous.version !== manifest.contentVersion ? {
         previousVersion: previous.version
       } : {},
@@ -39604,6 +39990,9 @@ async function applyContentUpdate(manifest, manifestUrl, options = {}) {
     pruneVersions(pointer);
     return {
       version: pointer.version,
+      ...pointer.sourceCommit ? {
+        sourceCommit: pointer.sourceCommit
+      } : {},
       ...pointer.previousVersion ? {
         previousVersion: pointer.previousVersion
       } : {},
@@ -39637,6 +40026,9 @@ function rollbackContentUpdate() {
       generatedAt: manifest.generatedAt,
       activatedAt: new Date().toISOString(),
       manifestUrl: active.manifestUrl,
+      ...manifest.sourceCommit ? {
+        sourceCommit: manifest.sourceCommit
+      } : {},
       previousVersion: active.version,
       knowledge: Boolean(manifest.knowledge && existsSync18(join23(previousPath, "knowledge.db"))),
       skills: Boolean(manifest.skills && existsSync18(join23(previousPath, "skills")))
@@ -39645,6 +40037,9 @@ function rollbackContentUpdate() {
 `, 384);
     return {
       version: next.version,
+      ...next.sourceCommit ? {
+        sourceCommit: next.sourceCommit
+      } : {},
       previousVersion: next.previousVersion,
       knowledge: next.knowledge,
       skills: next.skills,
@@ -39696,6 +40091,10 @@ function contentUpdateDisabled(configured) {
 function isNewerManifest(manifest, active) {
   if (!active)
     return true;
+  if (manifest.sourceCommit && active.sourceCommit)
+    return manifest.sourceCommit !== active.sourceCommit;
+  if (manifest.sourceCommit && !active.sourceCommit)
+    return true;
   if (manifest.contentVersion === active.version)
     return false;
   const generated = Date.parse(manifest.generatedAt);
@@ -39771,7 +40170,7 @@ function acquireLock() {
 }
 function staleLock(path) {
   try {
-    const stats = statSync6(path);
+    const stats = statSync7(path);
     const parsed = JSON.parse(readBoundedFileTextSyncNoFollow(path, 4 * 1024, "content update lock"));
     if (typeof parsed.pid === "number" && parsed.pid > 0) {
       try {
@@ -67344,16 +67743,18 @@ async function runContentUpdateCommand(parsed, workspace) {
     const status3 = contentStatus();
     if (!status3.active) {
       const knowledge = legacyKnowledgeDbPath();
-      console.log("content: bundled defaults");
+      console.log("content: not installed");
       console.log("active release: none");
       console.log(`knowledge: ${existsSync26(knowledge) ? knowledge : "not installed"}`);
-      console.log("skills: bundled");
+      console.log("skills: not installed");
       return 0;
     }
     console.log(`content: ${status3.active.version}`);
+    if (status3.active.sourceCommit)
+      console.log(`source commit: ${status3.active.sourceCommit}`);
     console.log(`activated: ${status3.active.activatedAt}`);
     console.log(`knowledge: ${status3.knowledgePath ?? "local fallback"}`);
-    console.log(`skills: ${status3.skillsPath ?? "bundled fallback"}`);
+    console.log(`skills: ${status3.skillsPath ?? "not installed"}`);
     console.log(`available versions: ${status3.versions.join(", ") || "none"}`);
     return 0;
   }
@@ -67381,6 +67782,8 @@ async function runContentUpdateCommand(parsed, workspace) {
 function printContentUpdateStatus(status2) {
   if (status2.state === "update_available") {
     console.log(`content update available: ${status2.active?.version ?? "none"} -> ${status2.manifest?.contentVersion}`);
+    if (status2.manifest?.sourceCommit)
+      console.log(`source commit: ${status2.manifest.sourceCommit}`);
     return 0;
   }
   if (status2.state === "up_to_date") {
@@ -68145,7 +68548,7 @@ __export(exports_csi_suite, {
   loadCsiCampaignConfig: () => loadCsiCampaignConfig,
   generateCsiBenchmarkSuite: () => generateCsiBenchmarkSuite
 });
-import { existsSync as existsSync27, readdirSync as readdirSync13, statSync as statSync7 } from "fs";
+import { existsSync as existsSync27, readdirSync as readdirSync13, statSync as statSync8 } from "fs";
 import { dirname as dirname12, isAbsolute as isAbsolute9, join as join35, relative as relative11, resolve as resolve11 } from "path";
 async function loadCsiCampaignConfig(path) {
   return normalizeCsiCampaignConfig(JSON.parse(await readBoundedFileText(path, CSI_CAMPAIGN_MAX_BYTES, "csi campaign config")));
@@ -68171,7 +68574,7 @@ async function generateCsiBenchmarkSuite(configInput, materialRoot) {
     if (config.isolation.backend === "host" && material.requiresTarget)
       throw new Error(`host csi challenge requires a live target and cannot run in host smoke mode: ${challenge.id}`);
     const promptPath = protectedPath(root, material.promptFile, `${challenge.id}.promptFile`);
-    if (!existsSync27(promptPath) || !statSync7(promptPath).isFile())
+    if (!existsSync27(promptPath) || !statSync8(promptPath).isFile())
       throw new Error(`missing prompt file for csi challenge: ${challenge.id}`);
     const prompt = readBoundedFileTextSync(promptPath, CSI_PROMPT_MAX_BYTES, `csi prompt ${challenge.id}`).trim();
     if (!prompt)
@@ -68180,7 +68583,7 @@ async function generateCsiBenchmarkSuite(configInput, materialRoot) {
       const source = protectedPath(root, file.source, `${challenge.id}.files[${index}].source`);
       if (!existsSync27(source))
         throw new Error(`missing input for csi challenge ${challenge.id}: ${file.source}`);
-      if (statSync7(source).isDirectory() && !listFiles(source).length)
+      if (statSync8(source).isDirectory() && !listFiles(source).length)
         throw new Error(`empty input directory for csi challenge ${challenge.id}: ${file.source}`);
       const digest2 = hashPath(source);
       if (file.sha256 && file.sha256.toLowerCase() !== digest2)
@@ -68200,14 +68603,14 @@ async function generateCsiBenchmarkSuite(configInput, materialRoot) {
         throw new Error(`missing required protected files for csi challenge ${challenge.id}: ${missing.join(", ")}`);
     }
     const executable = protectedPath(root, material.oracle.executable, `${challenge.id}.oracle.executable`);
-    if (!existsSync27(executable) || !statSync7(executable).isFile())
+    if (!existsSync27(executable) || !statSync8(executable).isFile())
       throw new Error(`missing oracle executable for csi challenge: ${challenge.id}`);
-    if ((statSync7(executable).mode & 73) === 0)
+    if ((statSync8(executable).mode & 73) === 0)
       throw new Error(`oracle executable is not executable for csi challenge: ${challenge.id}`);
     const antiCheatExecutable = material.antiCheat ? protectedPath(root, material.antiCheat.executable, `${challenge.id}.antiCheat.executable`) : undefined;
-    if (antiCheatExecutable && (!existsSync27(antiCheatExecutable) || !statSync7(antiCheatExecutable).isFile()))
+    if (antiCheatExecutable && (!existsSync27(antiCheatExecutable) || !statSync8(antiCheatExecutable).isFile()))
       throw new Error(`missing anti-cheat executable for csi challenge: ${challenge.id}`);
-    if (antiCheatExecutable && (statSync7(antiCheatExecutable).mode & 73) === 0)
+    if (antiCheatExecutable && (statSync8(antiCheatExecutable).mode & 73) === 0)
       throw new Error(`anti-cheat executable is not executable for csi challenge: ${challenge.id}`);
     if (config.isolation.backend === "docker" && !material.target)
       throw new Error(`docker csi challenge requires a pinned target image: ${challenge.id}`);
@@ -68416,7 +68819,7 @@ function protectedPath(root, path, name) {
   return resolved;
 }
 function listFiles(rootPath) {
-  if (!statSync7(rootPath).isDirectory())
+  if (!statSync8(rootPath).isDirectory())
     return [rootPath];
   return readdirSync13(rootPath).flatMap((name) => listFiles(join35(rootPath, name)));
 }
@@ -68539,6 +68942,36 @@ class BenchmarkDockerLifecycle {
     this.runner = runner;
   }
   async start() {
+    if (this.startPromise)
+      return this.startPromise;
+    const waitedForStop = Boolean(this.stopPromise);
+    if (this.stopPromise)
+      await this.stopPromise;
+    if (!waitedForStop && this.stateValue?.started && !this.stateValue.cleaned && this.planValue) {
+      return {
+        backend: new KaliContainerBackend({
+          workspace: this.workspace,
+          image: DEFAULT_KALI_IMAGE,
+          containerName: this.planValue.names.agent,
+          processRunner: (command, args2) => this.runner(command, args2)
+        }),
+        state: this.stateValue,
+        plan: this.planValue
+      };
+    }
+    if (this.stateValue && !this.stateValue.cleaned) {
+      const previous = await this.stopUnlocked();
+      if (previous && !previous.cleaned)
+        throw new Error("previous benchmark Docker resources could not be cleaned up");
+    }
+    this.startPromise = this.startUnlocked();
+    try {
+      return await this.startPromise;
+    } finally {
+      this.startPromise = undefined;
+    }
+  }
+  async startUnlocked() {
     const processRunner = (command, args2) => this.runner(command, args2);
     const image = await new KaliContainerBackend({
       workspace: this.workspace,
@@ -68546,14 +68979,17 @@ class BenchmarkDockerLifecycle {
       processRunner
     }).resolveImage();
     if (!image.exists)
-      throw new Error(`benchmark agent image is missing: ${DEFAULT_KALI_IMAGE}`);
+      throw new Error(image.error ?? `benchmark agent image is missing: ${DEFAULT_KALI_IMAGE}`);
+    if (image.error)
+      throw new Error(image.error);
     const agentImageId = image.id?.trim() ?? "";
     if (!/^sha256:[a-f0-9]{64}$/i.test(agentImageId))
       throw new Error(`docker returned an unpinned agent image id: ${agentImageId || "empty"}`);
     const agentImageContract = image.contract?.trim() ?? "";
     if (agentImageContract !== KALI_IMAGE_CONTRACT)
       throw new Error(`benchmark agent image does not satisfy the current capability contract: ${agentImageContract || "missing"}`);
-    const plan = buildBenchmarkDockerPlan(this.manifest, this.workspace, this.runId, agentImageId);
+    const targetImage = await resolveTargetImage(this.manifest, this.runner);
+    const plan = buildBenchmarkDockerPlan(this.manifest, this.workspace, this.runId, agentImageId, targetImage);
     this.planValue = plan;
     const state = {
       network: plan.names.network,
@@ -68561,6 +68997,7 @@ class BenchmarkDockerLifecycle {
       agentContainer: plan.names.agent,
       agentImageId,
       agentImageContract,
+      targetImage,
       started: false,
       antiCheatApplied: false,
       cleaned: false,
@@ -68592,27 +69029,49 @@ class BenchmarkDockerLifecycle {
       };
     } catch (error) {
       state.errors.push(error instanceof Error ? error.message : String(error));
-      await this.stop();
+      await this.stopUnlocked();
       throw error;
     }
   }
   async stop() {
+    if (this.startPromise)
+      await this.startPromise.catch(() => {
+        return;
+      });
+    if (this.stopPromise)
+      return this.stopPromise;
+    this.stopPromise = this.stopUnlocked();
+    try {
+      return await this.stopPromise;
+    } finally {
+      this.stopPromise = undefined;
+    }
+  }
+  async stopUnlocked() {
     const state = this.stateValue;
     const plan = this.planValue;
     if (!state || !plan || state.cleaned)
       return state;
-    const agentState = await this.inspectState(plan.names.agent);
-    const targetState = await this.inspectState(plan.names.target);
+    const [agentState, targetState] = await Promise.all([this.inspectState(plan.names.agent), this.inspectState(plan.names.target)]);
     if (agentState)
       state.agentState = agentState;
     if (targetState)
       state.targetState = targetState;
+    let cleaned = true;
     for (const args2 of plan.cleanup) {
-      const result = await this.runner("docker", args2);
-      if (result.exitCode !== 0 && result.stderr.trim())
-        state.errors.push(result.stderr.trim().slice(0, 500));
+      try {
+        const result = await this.runner("docker", args2);
+        if (result.exitCode !== 0 && !resourceDoesNotExist(result)) {
+          cleaned = false;
+          if (result.stderr.trim())
+            state.errors.push(result.stderr.trim().slice(0, 500));
+        }
+      } catch (error) {
+        cleaned = false;
+        state.errors.push(error instanceof Error ? error.message.slice(0, 500) : String(error).slice(0, 500));
+      }
     }
-    state.cleaned = true;
+    state.cleaned = cleaned;
     return state;
   }
   async requiredDocker(args2, operation) {
@@ -68621,10 +69080,10 @@ class BenchmarkDockerLifecycle {
       throw new Error(result.stderr || `failed to ${operation}`);
   }
   async inspectState(name) {
-    const result = await this.runner("docker", ["inspect", "--format", "{{json .State}}", name]);
-    if (result.exitCode !== 0)
-      return;
     try {
+      const result = await this.runner("docker", ["inspect", "--format", "{{json .State}}", name]);
+      if (result.exitCode !== 0)
+        return;
       const state = JSON.parse(result.stdout);
       if (typeof state.Running !== "boolean" || typeof state.ExitCode !== "number")
         return;
@@ -68637,7 +69096,7 @@ class BenchmarkDockerLifecycle {
     }
   }
 }
-function buildBenchmarkDockerPlan(manifest, workspace, runId, agentImageId) {
+function buildBenchmarkDockerPlan(manifest, workspace, runId, agentImageId, targetImageOverride) {
   if (manifest.isolation.backend !== "docker")
     throw new Error("benchmark docker plan requires isolation.backend=docker");
   if (manifest.isolation.network !== "target_only" || manifest.isolation.internet !== "disabled") {
@@ -68664,12 +69123,13 @@ function buildBenchmarkDockerPlan(manifest, workspace, runId, agentImageId) {
     throw new Error("docker benchmark diskMb is not enforceable for a bind-mounted scratch workspace");
   const common = ["--security-opt", "no-new-privileges:true", ...resources?.pids ? ["--pids-limit", String(resources.pids)] : []];
   const resourceArgs = [...resources?.cpus ? ["--cpus", String(resources.cpus)] : [], ...resources?.memoryMb ? ["--memory", `${resources.memoryMb}m`] : []];
-  const targetImage = pinnedImage(manifest.challenge.targetImage, manifest.challenge.targetImageDigest);
+  const targetImage = targetImageOverride ?? pinnedImage(manifest.challenge.targetImage, manifest.challenge.targetImageDigest);
   const targetStart = ["run", "-d", "--name", names.target, "--network", names.network, "--network-alias", "target", "--cap-drop", "ALL", "--cap-add", "NET_BIND_SERVICE", ...common, ...resourceArgs, targetImage, ...manifest.challenge.targetCommand ?? []];
   const resolvedWorkspace = resolve12(workspace);
   const agentStart = ["run", "-d", "--name", names.agent, "--network", names.network, "--workdir", "/workspace", "--volume", `${resolvedWorkspace}:/workspace:rw`, "--volume", "/workspace/.farai", "--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=512m", "--tmpfs", "/root:rw,nosuid,nodev,size=256m", "--tmpfs", "/run:rw,nosuid,nodev,size=64m", "--cap-drop", "ALL", "--cap-add", "NET_ADMIN", "--cap-add", "NET_RAW", ...common, ...resourceArgs, agentImageId, "sleep", "infinity"];
   return {
     names,
+    targetImage,
     networkCreate: ["network", "create", "--internal", "--label", "org.farai.benchmark=true", names.network],
     targetStart,
     agentStart,
@@ -68686,6 +69146,51 @@ function buildBenchmarkDockerPlan(manifest, workspace, runId, agentImageId) {
     cleanup: [["rm", "-f", "-v", names.agent], ["rm", "-f", "-v", names.target], ["network", "rm", names.network]]
   };
 }
+async function resolveTargetImage(manifest, runner) {
+  if (!manifest.challenge.targetImage || !manifest.challenge.targetImageDigest)
+    throw new Error("docker benchmark requires a pinned target image");
+  const pinned = pinnedImage(manifest.challenge.targetImage, manifest.challenge.targetImageDigest);
+  const exact = await runner("docker", ["image", "inspect", pinned]);
+  if (exact.exitCode === 0)
+    return imageIdFromInspect(exact.stdout) ?? pinned;
+  const base = manifest.challenge.targetImage.split("@")[0];
+  const tagged = await runner("docker", ["image", "inspect", base]);
+  if (tagged.exitCode === 0) {
+    const imageId = imageIdForDigest(tagged.stdout, pinned);
+    if (imageId)
+      return imageId;
+  }
+  const details = [exact.stderr, tagged.stderr].map((value) => value.trim()).find(Boolean);
+  throw new Error(`benchmark target image is unavailable locally: ${pinned}; build or load the pinned target image before running the benchmark${details ? ` (${details.slice(0, 300)})` : ""}`);
+}
+function imageIdForDigest(raw, pinned) {
+  try {
+    const images = JSON.parse(raw);
+    const image = images[0];
+    if (!image || !Array.isArray(image.RepoDigests))
+      return;
+    const [repository, digest2] = pinned.split("@");
+    const repositoryWithoutTag = repository?.replace(/:[^/:]+$/, "");
+    const matches2 = image.RepoDigests.some((value) => typeof value === "string" && (value.toLowerCase() === pinned.toLowerCase() || repositoryWithoutTag && digest2 && value.toLowerCase() === `${repositoryWithoutTag}@${digest2}`.toLowerCase()));
+    if (!matches2 || typeof image.Id !== "string" || !/^sha256:[a-f0-9]{64}$/i.test(image.Id))
+      return;
+    return image.Id;
+  } catch {
+    return;
+  }
+}
+function imageIdFromInspect(raw) {
+  try {
+    const id2 = JSON.parse(raw)[0]?.Id;
+    return typeof id2 === "string" && /^sha256:[a-f0-9]{64}$/i.test(id2) ? id2 : undefined;
+  } catch {
+    return;
+  }
+}
+function resourceDoesNotExist(result) {
+  return /no such (container|network|object)|(?:container|network)\s+[^\n]*\bnot found\b/i.test(`${result.stdout}
+${result.stderr}`);
+}
 function pinnedImage(image, digest2) {
   const normalizedDigest = digest2.startsWith("sha256:") ? digest2 : `sha256:${digest2}`;
   if (!/^sha256:[a-f0-9]{64}$/i.test(normalizedDigest))
@@ -70377,12 +70882,15 @@ async function setup(args2) {
     console.log("[*] skipping Docker image build");
   }
   if (!parsed.skipKnowledge) {
-    console.log("[*] building Farai knowledge base");
-    const code = await (await Promise.resolve().then(() => (init_command(), exports_command))).runKbCommand(["build", "all"]);
-    if (code !== 0) {
-      process.exitCode = code;
-      console.error("[!] knowledge base build failed");
-      return;
+    const contentInstalled = await syncContentForSetup(process.cwd());
+    if (!contentInstalled) {
+      console.log("[*] building Farai knowledge base");
+      const code = await (await Promise.resolve().then(() => (init_command(), exports_command))).runKbCommand(["build", "all"]);
+      if (code !== 0) {
+        process.exitCode = code;
+        console.error("[!] knowledge base build failed");
+        return;
+      }
     }
   } else {
     console.log("[*] skipping knowledge base build");
@@ -70390,6 +70898,30 @@ async function setup(args2) {
   console.log("[+] setup complete");
   console.log("[+] run `farai doctor` to verify the environment");
 }
+async function syncContentForSetup(workspace) {
+  const {
+    applyContentUpdate: applyContentUpdate2,
+    checkContentUpdate: checkContentUpdate2,
+    contentStatus: contentStatus2
+  } = await Promise.resolve().then(() => (init_updater(), exports_updater));
+  try {
+    const status2 = await checkContentUpdate2({
+      workspace,
+      force: true
+    });
+    if (status2.state === "update_available" && status2.manifest) {
+      console.log(`[*] syncing Farai content ${status2.manifest.contentVersion}`);
+      const applied = await applyContentUpdate2(status2.manifest, status2.manifestUrl);
+      const parts = [applied.knowledge ? "knowledge" : undefined, applied.skills ? "skills" : undefined].filter(Boolean).join(" + ");
+      console.log(`[+] content: ${applied.version}${parts ? ` (${parts})` : ""}`);
+    } else if (status2.state === "error") {
+      console.error(`[!] content sync unavailable: ${status2.error ?? "unknown error"}`);
+    }
+  } catch (error) {
+    console.error(`[!] content sync failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return Boolean(contentStatus2().active?.knowledge);
+}
 async function models(args2 = []) {
   const parsed = parseModelArguments(args2);
   ensureDefaultUserConfig();
@@ -70727,5 +71259,5 @@ Examples:
 `);
 }
 
-//# debugId=59D0DF40CE3D0BDB64756E2164756E21
+//# debugId=ABD822216062EDDD64756E2164756E21
 //# sourceMappingURL=index.js.map