@north-light/crouter 0.3.193 → 0.3.195

package/dist/pages/elements/table.js

@@ -18,8 +18,8 @@
  */
 import { registerElement } from '../register.js';
 import { readSlotConfig, readSlotId } from '../slot-config.js';
-import { artifactData, respond } from '../host.js';
-import { anchorLabel, findComment, setComment } from '../comments.js';
+import { artifactData, respond, savedIds, savedResponse } from '../host.js';
+import { adoptComments, anchorLabel, findComment, setComment } from '../comments.js';
 const COMMENT_BUBBLE = 'M3.25 3.5h9.5A1.75 1.75 0 0 1 14.5 5.25v5A1.75 1.75 0 0 1 12.75 12H7.4l-3.15 2.36A.5.5 0 0 1 3.5 14v-2H3.25A1.75 1.75 0 0 1 1.5 10.25v-5A1.75 1.75 0 0 1 3.25 3.5Z';
 const STYLE = `
   :host {
@@ -421,6 +421,7 @@ class CrtrTableElement extends HTMLElement {
             return;
         }
         this.#rows = config.rows;
+        this.#hydrate();
         this.#renderTable();
     }
     disconnectedCallback() {
@@ -440,8 +441,36 @@ class CrtrTableElement extends HTMLElement {
             return;
         }
         this.#rows = rows.rows;
+        this.#hydrate();
         this.#renderTable();
     }
+    /**
+     * Seed local state from the answer the host is already holding, so a reopened page shows
+     * the rows and columns that were picked. It runs once the rows are known — after a `source`
+     * load, not before — because a saved id is only honoured while it still names something on
+     * screen. The select modes are re-imposed for the same reason.
+     */
+    #hydrate() {
+        if (this.#slotId === undefined)
+            return;
+        const saved = savedResponse(this.#slotId);
+        if (saved === undefined)
+            return;
+        const rows = this.#orderRows(savedIds(saved.selectedRowIds));
+        const columns = this.#orderColumns(savedIds(saved.selectedColumnIds));
+        this.#selectedRowIds = this.#rowSelect === 'none' ? [] : this.#rowSelect === 'single' ? rows.slice(0, 1) : rows;
+        this.#selectedColumnIds =
+            this.#columnSelect === 'none' ? [] : this.#columnSelect === 'single' ? columns.slice(0, 1) : columns;
+        const rowIds = new Set(this.#rows.map((row) => row.id));
+        const columnIds = new Set((this.#config?.columns ?? []).map((column) => column.id));
+        this.#comments = adoptComments(saved.comments).filter((comment) => {
+            if (comment.anchor.kind === 'row')
+                return rowIds.has(comment.anchor.rowId);
+            if (comment.anchor.kind === 'column')
+                return columnIds.has(comment.anchor.columnId);
+            return true;
+        });
+    }
     // ── the response ───────────────────────────────────────────────────────────────────────
     get #rowSelect() {
         return this.#config?.rowSelect ?? 'none';

package/dist/pages/elements/text.js

@@ -24,8 +24,8 @@
  */
 import { registerElement } from '../register.js';
 import { readSlotConfig, readSlotId } from '../slot-config.js';
-import { respond } from '../host.js';
-import { findComment, setComment } from '../comments.js';
+import { respond, savedResponse } from '../host.js';
+import { adoptComments, findComment, setComment } from '../comments.js';
 const WHOLE = { kind: 'whole' };
 const WHOLE_TARGET = 'the whole passage';
 const RANGE_TARGET = 'the selected text';
@@ -622,6 +622,7 @@ class CrtrTextElement extends HTMLElement {
         this.#config = read.config;
         this.#slotId = readSlotId(this);
         this.#text = read.config.initialText;
+        this.#hydrate();
         this.#editing = read.config.editable === true && this.#text.length === 0;
         this.#renderToolbar();
         this.#renderSurface();
@@ -630,6 +631,22 @@ class CrtrTextElement extends HTMLElement {
     disconnectedCallback() {
         document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
     }
+    /**
+     * Seed local state from the answer the host is already holding, so a reopened page shows
+     * the edited words and the comments on them rather than the agent's original text. An
+     * uneditable slot keeps its authored text — only comments carry over — because a saved
+     * edit there could not have come from this control.
+     */
+    #hydrate() {
+        if (this.#slotId === undefined)
+            return;
+        const saved = savedResponse(this.#slotId);
+        if (saved === undefined)
+            return;
+        if (this.#config.editable === true && typeof saved.text === 'string')
+            this.#text = saved.text;
+        this.#comments = adoptComments(saved.comments);
+    }
     /** The complete current response — what every change hands `respond()`. */
     #response() {
         return { text: this.#text, edited: this.#text !== this.#config.initialText, comments: this.#comments };

package/dist/pages/host.d.ts

@@ -16,6 +16,12 @@
  *    the host autosave the partial map; it does not resolve the ticket. Only the pager's
  *    submit affordance calls `submit()`, which posts the complete map once.
  *
+ * `respond()` has one counterpart, `savedResponse()`: the host hands back the response it is
+ * currently holding for a slot, so a page reopened after a partial answer re-mounts SHOWING
+ * that answer instead of blank. Every response-bearing element reads it at mount and seeds
+ * its visible state from it — that is what keeps "what submit sends" and "what the screen
+ * shows" the same thing.
+ *
  * The host is optional at the type level (`window.crtr?`) because a page can be opened
  * bare — dropped in a browser, or rendered by a host that installs nothing. Elements read
  * the bridge through the accessors below rather than touching `window.crtr` directly, so
@@ -42,6 +48,12 @@ export interface CrtrHost {
      * partial map. Called on every user change. NOT ticket resolution.
      */
     respond(slotId: string, response: SlotResponse): void;
+    /**
+     * The response the host currently holds for this slot — an autosaved partial answer on a
+     * reopened page, or the published answer on a resolved one. `undefined` when the host has
+     * nothing for the slot. Elements read it at mount; it is the inbound half of `respond`.
+     */
+    savedResponse(slotId: string): SlotResponse | undefined;
     /** Posts the complete response map once. Only the pager's submit affordance calls it. */
     submit(): Promise<void>;
     /** Flushes the pending autosave of the partial map. */
@@ -98,6 +110,20 @@ export declare function host(): CrtrHost | undefined;
  * so an unavailable host only means the answer is not being persisted.
  */
 export declare function respond(slotId: string, response: SlotResponse): HostCall;
+/**
+ * The response the host already holds for this slot, or `undefined` when it holds none — a
+ * bare page, a first open, or a host without the channel. Elements call this once at mount
+ * and seed their visible state from it, so a reopened page shows the answers the host would
+ * submit rather than an empty form beside a full response map.
+ *
+ * `T` is asserted, not verified, exactly like `readSlotConfig`'s config: the host's saved map
+ * was validated against this slot's kind before it was stored. What is not guaranteed is that
+ * a host implements the channel at all, which is what the `undefined` covers — so seed with
+ * the same defensiveness you would give any outside value (`savedIds`, `adoptComments`).
+ */
+export declare function savedResponse<T extends SlotResponse = SlotResponse>(slotId: string): T | undefined;
+/** The string ids of a saved selection field, with anything else in it dropped. */
+export declare function savedIds(value: unknown): string[];
 /**
  * Posts the complete response map once, resolving the ticket. Only the pager's submit
  * affordance calls this.

package/dist/pages/host.js

@@ -16,6 +16,12 @@
  *    the host autosave the partial map; it does not resolve the ticket. Only the pager's
  *    submit affordance calls `submit()`, which posts the complete map once.
  *
+ * `respond()` has one counterpart, `savedResponse()`: the host hands back the response it is
+ * currently holding for a slot, so a page reopened after a partial answer re-mounts SHOWING
+ * that answer instead of blank. Every response-bearing element reads it at mount and seeds
+ * its visible state from it — that is what keeps "what submit sends" and "what the screen
+ * shows" the same thing.
+ *
  * The host is optional at the type level (`window.crtr?`) because a page can be opened
  * bare — dropped in a browser, or rendered by a host that installs nothing. Elements read
  * the bridge through the accessors below rather than touching `window.crtr` directly, so
@@ -52,6 +58,33 @@ export function respond(slotId, response) {
         return { status: 'failed', reason: reasonOf(error) };
     }
 }
+/**
+ * The response the host already holds for this slot, or `undefined` when it holds none — a
+ * bare page, a first open, or a host without the channel. Elements call this once at mount
+ * and seed their visible state from it, so a reopened page shows the answers the host would
+ * submit rather than an empty form beside a full response map.
+ *
+ * `T` is asserted, not verified, exactly like `readSlotConfig`'s config: the host's saved map
+ * was validated against this slot's kind before it was stored. What is not guaranteed is that
+ * a host implements the channel at all, which is what the `undefined` covers — so seed with
+ * the same defensiveness you would give any outside value (`savedIds`, `adoptComments`).
+ */
+export function savedResponse(slotId) {
+    const bridge = host();
+    if (typeof bridge?.savedResponse !== 'function')
+        return undefined;
+    try {
+        const saved = bridge.savedResponse(slotId);
+        return typeof saved === 'object' && saved !== null && !Array.isArray(saved) ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The string ids of a saved selection field, with anything else in it dropped. */
+export function savedIds(value) {
+    return Array.isArray(value) ? value.filter((id) => typeof id === 'string') : [];
+}
 /**
  * Posts the complete response map once, resolving the ticket. Only the pager's submit
  * affordance calls this.

package/dist/pi-extensions/canvas-bash-valve.d.ts

@@ -3,6 +3,8 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /** Seconds a leading `sleep ...` will block for, or null when the command does
  *  not open with a sleep (or its duration isn't statically knowable). */
 export declare function leadingSleepSeconds(command: string): number | null;
-/** The valve's BashOperations backend. */
-export declare function createValveOperations(nodeId: string, contextDir: string): BashOperations;
+/** The valve's BashOperations backend. Each tool execution closes over its own
+ * `takePurpose`, so concurrent calls cannot exchange labels. It is consumed even
+ * when the command is invalid or refused, leaving no state to leak later. */
+export declare function createValveOperations(nodeId: string, contextDir: string, takePurpose?: () => string | null): BashOperations;
 export default function (pi: ExtensionAPI): void;

package/dist/pi-extensions/canvas-bash-valve.js

@@ -27,7 +27,7 @@
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
-import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId } from '../core/bash-jobs.js';
+import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId, normalizeBashJobPurpose } from '../core/bash-jobs.js';
 import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
@@ -203,11 +203,14 @@ function resolveExecutionCwd(cwd) {
         warning: `[working directory no longer exists: ${cwd}; running from ${fallback}]\n`,
     };
 }
-/** The valve's BashOperations backend. */
-export function createValveOperations(nodeId, contextDir) {
+/** The valve's BashOperations backend. Each tool execution closes over its own
+ * `takePurpose`, so concurrent calls cannot exchange labels. It is consumed even
+ * when the command is invalid or refused, leaving no state to leak later. */
+export function createValveOperations(nodeId, contextDir, takePurpose = () => null) {
     return {
         exec: (command, cwd, { onData, signal, timeout, env }) => {
             return new Promise((resolve, reject) => {
+                const purpose = takePurpose();
                 if (signal?.aborted) {
                     reject(new Error('aborted'));
                     return;
@@ -222,6 +225,8 @@ export function createValveOperations(nodeId, contextDir) {
                 writeFileSync(paths.cmdSh, command);
                 writeFileSync(paths.jobLog, '');
                 writeFileSync(paths.jobRun, '');
+                if (purpose !== null)
+                    writeFileSync(paths.jobPurpose, purpose);
                 let offset = 0;
                 let settled = false;
                 let pgid;
@@ -357,8 +362,10 @@ export function createValveOperations(nodeId, contextDir) {
 // parsing partial JSON can show the label while the command is still being
 // written, rather than after the call is complete and about to finish.
 //
-// The execute path ignores it entirely — this is a labelling channel, not an
-// input. Optional, so a model that omits it behaves exactly as before.
+// The command execution path ignores it as shell input — this remains a
+// labelling channel, not an execution parameter. The valve only persists the
+// label beside a background job. Optional, so a model that omits it behaves
+// exactly as before.
 //
 // Upstream ask: pi's own bash tool should carry this (Claude Code's bash tool
 // has shipped an equivalent `description` field for years). Until it does, the
@@ -386,6 +393,18 @@ function withPurpose(definition) {
         }),
     };
 }
+/** Bind each purpose directly to its own tool execution. Pi may preflight a
+ * batch before starting its calls, so a shared "next purpose" slot could give
+ * a concurrent call the wrong label. */
+function createPurposeValveToolDefinition(nodeId, contextDir, cwd) {
+    const schemaDefinition = withPurpose(createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir) }));
+    const execute = (toolCallId, params, signal, onUpdate, ctx) => {
+        const purpose = normalizeBashJobPurpose(params['purpose']);
+        const definition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir, () => purpose) });
+        return definition.execute(toolCallId, params, signal, onUpdate, ctx);
+    };
+    return { ...schemaDefinition, execute };
+}
 export default function (pi) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
@@ -399,7 +418,6 @@ export default function (pi) {
     // is built against. registerTool replaces the builtin by name; re-firing on
     // every session_start is idempotent (last registration wins).
     pi.on('session_start', (_event, ctx) => {
-        const operations = createValveOperations(nodeId, contextDir);
-        pi.registerTool(withPurpose(createBashToolDefinition(ctx.cwd, { operations })));
+        pi.registerTool(createPurposeValveToolDefinition(nodeId, contextDir, ctx.cwd));
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.193",
+  "version": "0.3.195",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.193",
+  "version": "0.3.195",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.193",
+      "version": "0.3.195",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/scripts/install-runtime.mjs

@@ -2,6 +2,7 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ENTRY_NAMES, GENERATION_ID, MANIFEST_KEYS, PACKAGE_NAME, MANIFEST_SCHEMA, contained, isSealed, publishedMarkerPath, runtimeHome, sortInventory, validateManifestShape } from '../bin/runtime-generation-manifest.mjs';
@@ -11,9 +12,20 @@ const PACKAGE_ROOT = process.argv[2] ? resolve(process.argv[2]) : resolve(dirnam
 const RUNTIME_HOME = runtimeHome();
 const GENERATIONS = join(RUNTIME_HOME, 'generations');
 const LOCK = join(RUNTIME_HOME, 'install.lock');
+const LOCK_OWNER_FILE = 'owner.json';
 const RUNTIME_LOCK = 'runtime.lock.json';
 const KEEP_RECENT_GENERATIONS = 3;
 const FS_CONCURRENCY = 64;
+// How long an install.lock with no readable owner record is given the
+// benefit of the doubt (the owner is mid-write, or on an ancient version of
+// this script that never wrote one) before it is treated as abandoned.
+const STALE_LOCK_RECORD_THRESHOLD_MS = 15 * 60 * 1000;
+// How long a `.staging-*`/`.archive-*` temp dir sits before the sweep in
+// step 4 treats it as wreckage from an earlier killed install rather than
+// work in progress under a lock we don't hold (impossible while we hold the
+// lock, but a conservative margin costs nothing).
+const STALE_TEMP_DIR_THRESHOLD_MS = 60 * 60 * 1000;
+const LOCK_ACQUIRE_MAX_ATTEMPTS = 50;
 
 function run(command, args, cwd, capture = false, env = process.env) {
   return new Promise((resolveRun, reject) => {
@@ -235,14 +247,162 @@ async function pruneGenerations() {
   }
 }
 
-async function install() {
-  await mkdir(GENERATIONS, { recursive: true });
+/** A process's start time as `ps` reports it — the cheap, boot-unique-enough
+ *  fellow-traveler of a pid that lets a reused pid be told apart from the
+ *  process that actually wrote a lock owner record. Empty string when the
+ *  pid does not exist (or `ps` cannot be run), never rejects. */
+async function pidStartTime(pid) {
+  const output = await probe('ps', ['-o', 'lstart=', '-p', String(pid)], RUNTIME_HOME);
+  return output.trim();
+}
+
+/** Whether `pid` currently identifies a live process, from this user's
+ *  vantage point. `EPERM` means the pid exists but is owned by someone
+ *  else — still alive, just not ours to signal. */
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+/** Write the lock owner record via temp-file + rename so a concurrent reader
+ *  never observes a half-written file. Must be called only once `LOCK` is
+ *  known to be ours (immediately after `mkdir(LOCK)` succeeds). */
+async function writeLockOwner(lockDir) {
+  const owner = { pid: process.pid, startTime: await pidStartTime(process.pid), hostname: hostname(), startedAt: new Date().toISOString() };
+  const temporary = join(lockDir, `.${LOCK_OWNER_FILE}.${process.pid}-${Date.now()}.tmp`);
+  await writeFile(temporary, JSON.stringify(owner));
+  await rename(temporary, join(lockDir, LOCK_OWNER_FILE));
+}
+
+async function readLockOwner(lockDir) {
+  try {
+    const owner = JSON.parse(await readFile(join(lockDir, LOCK_OWNER_FILE), 'utf8'));
+    return Number.isInteger(owner?.pid) ? owner : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True only when `owner`'s pid is both alive AND (when a start time was
+ *  recorded) still the same process that wrote the record — a recycled pid
+ *  must not masquerade as a live owner. */
+async function ownerIsAlive(owner) {
+  if (!owner || !pidAlive(owner.pid)) return false;
+  if (!owner.startTime) return true;
+  const currentStartTime = await pidStartTime(owner.pid);
+  return currentStartTime === '' || currentStartTime === owner.startTime;
+}
+
+/** Take `LOCK`, reclaiming it first if its owner is provably dead. A dead
+ *  owner is reclaimed unconditionally; a missing/corrupt owner record is
+ *  reclaimed only once the lock dir is older than a conservative threshold
+ *  (it may belong to a process that has not written its record yet). The
+ *  reclaim itself is race-safe: the stale dir is renamed to a private,
+ *  unique path first, and only the process whose rename wins takes the
+ *  fresh lock — a loser simply retries the ordinary contended path rather
+ *  than deleting a dir a concurrent winner might still be reading. */
+async function acquireLock() {
+  for (let attempt = 0; attempt < LOCK_ACQUIRE_MAX_ATTEMPTS; attempt++) {
+    try {
+      await mkdir(LOCK);
+      await writeLockOwner(LOCK);
+      return;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const owner = await readLockOwner(LOCK);
+      if (owner && (await ownerIsAlive(owner))) {
+        throw new Error(`runtime installer lock is held by a live process: pid=${owner.pid} started=${owner.startTime || 'unknown'} host=${owner.hostname || 'unknown'}; refusing to install concurrently`);
+      }
+      if (!owner) {
+        let stat;
+        try {
+          stat = await lstat(LOCK);
+        } catch (statError) {
+          if (statError?.code === 'ENOENT') continue; // lock vanished between mkdir and lstat; retry
+          throw statError;
+        }
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs < STALE_LOCK_RECORD_THRESHOLD_MS) {
+          throw new Error(`runtime installer lock exists without a readable owner record and is only ${Math.round(ageMs / 1000)}s old: ${LOCK}; inspect and remove only after confirming no installation is running`);
+        }
+      }
+      const graveyard = join(RUNTIME_HOME, `.lock-stale-${process.pid}-${Date.now()}`);
+      try {
+        await rename(LOCK, graveyard);
+      } catch (renameError) {
+        if (renameError?.code === 'ENOENT') continue; // another process already reclaimed it; fall back to the contended path
+        throw renameError;
+      }
+      process.stderr.write(`runtime installer: reclaimed a stale lock (dead owner pid=${owner?.pid ?? 'unknown'})\n`);
+      await removeStage(graveyard);
+      // Loop back and take the now-vacant lock.
+    }
+  }
+  throw new Error(`runtime installer lock: gave up after ${LOCK_ACQUIRE_MAX_ATTEMPTS} contended attempts: ${LOCK}`);
+}
+
+/** Sweep `.staging-*`/`.archive-*` temp dirs left behind by an install that
+ *  was killed before its own `finally` (or signal handler) could run. Only
+ *  called once this process holds `LOCK`, so any dir old enough to clear
+ *  the threshold cannot belong to a still-running install. */
+async function sweepOrphanTempDirs() {
+  let entries;
   try {
-    await mkdir(LOCK);
+    entries = await readdir(RUNTIME_HOME, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^\.(?:staging|archive)-/.test(entry.name)) continue;
+    const absolute = join(RUNTIME_HOME, entry.name);
+    let stat;
+    try {
+      stat = await lstat(absolute);
+    } catch {
+      continue;
+    }
+    if (Date.now() - stat.mtimeMs < STALE_TEMP_DIR_THRESHOLD_MS) continue;
+    process.stderr.write(`runtime installer: sweeping orphan temp dir from an earlier aborted install: ${absolute}\n`);
+    await removeStage(absolute);
+  }
+}
+
+// Populated as install() proceeds so a SIGINT/SIGTERM handler can undo
+// exactly what the normal `finally` below would have undone. SIGKILL
+// remains uncatchable, which is exactly why acquireLock() can reclaim.
+const cleanupState = { lockTaken: false, stage: undefined, archiveDir: undefined, publishedRoot: undefined, committed: false, temporary: undefined, id: undefined, exiting: false };
+
+async function cleanupOnSignal(signal) {
+  if (cleanupState.exiting) return;
+  cleanupState.exiting = true;
+  process.stderr.write(`runtime installer: received ${signal}, cleaning up before exit\n`);
+  try {
+    if (cleanupState.temporary) await rm(cleanupState.temporary, { force: true });
+    if (cleanupState.stage) await removeStage(cleanupState.stage);
+    if (cleanupState.publishedRoot && !cleanupState.committed) {
+      await removeStage(cleanupState.publishedRoot);
+      if (cleanupState.id) await rm(publishedMarkerPath(GENERATIONS, cleanupState.id), { force: true });
+    }
+    if (cleanupState.archiveDir) await rm(cleanupState.archiveDir, { recursive: true, force: true });
+    if (cleanupState.lockTaken) await rm(LOCK, { recursive: true, force: true });
   } catch (error) {
-    if (error?.code === 'EEXIST') throw new Error(`runtime installer lock exists: ${LOCK}; inspect and remove only after confirming no installation is running`);
-    throw error;
+    process.stderr.write(`runtime installer: cleanup on ${signal} failed: ${error?.message ?? error}\n`);
   }
+  process.exit(1);
+}
+
+process.on('SIGINT', () => { cleanupOnSignal('SIGINT'); });
+process.on('SIGTERM', () => { cleanupOnSignal('SIGTERM'); });
+
+async function install() {
+  await mkdir(GENERATIONS, { recursive: true });
+  await acquireLock();
+  cleanupState.lockTaken = true;
+  await sweepOrphanTempDirs();
   let stage;
   let archiveDir;
   let publishedRoot;
@@ -251,9 +411,11 @@ async function install() {
   let id;
   try {
     archiveDir = await mkdtemp(join(RUNTIME_HOME, '.archive-'));
+    cleanupState.archiveDir = archiveDir;
     const archive = await pack(archiveDir);
     const archiveHash = digest(await readFile(archive));
     stage = await mkdtemp(join(RUNTIME_HOME, '.staging-'));
+    cleanupState.stage = stage;
     await run('tar', ['-xzf', archive, '--strip-components=1', '-C', stage], PACKAGE_ROOT);
     await copyFile(join(stage, RUNTIME_LOCK), join(stage, 'package-lock.json'));
     // Humanloop's postinstall only prewarms its external termrender cache; runtime rendering retries lazily with a plaintext fallback.
@@ -265,6 +427,7 @@ async function install() {
     const pkg = JSON.parse(await readFile(join(stage, 'package.json'), 'utf8'));
     const files = sortInventory(await inventory(stage));
     id = digest(`${archiveHash}\n${digest(await readFile(join(stage, 'package-lock.json')))}\n${digest(JSON.stringify(files))}\n${process.version}\n${process.platform}\n${process.arch}\ninstaller-schema-1`);
+    cleanupState.id = id;
     const finalRoot = join(GENERATIONS, id);
     const manifest = {
       schema: MANIFEST_SCHEMA,
@@ -294,8 +457,10 @@ async function install() {
       await chmod(stage, 0o755);
       await rename(stage, finalRoot);
       publishedRoot = finalRoot;
+      cleanupState.publishedRoot = publishedRoot;
       await chmod(finalRoot, 0o555);
       stage = undefined;
+      cleanupState.stage = undefined;
       await validatePublished(finalRoot, id);
     }
     // Only after the full-hash check above has succeeded for this exact id —
@@ -303,9 +468,11 @@ async function install() {
     await markPublished(GENERATIONS, id);
     const selected = join(RUNTIME_HOME, 'selected');
     temporary = join(RUNTIME_HOME, `.selected-${process.pid}-${Date.now()}`);
+    cleanupState.temporary = temporary;
     await symlink(`generations/${id}`, temporary);
     await rename(temporary, selected);
     committed = true;
+    cleanupState.committed = true;
     try {
       await pruneGenerations();
     } catch (error) {