@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/runs/agent-tmpdir.js

@@ -1,53 +1,12 @@
 /**
- * Task-scoped temp directory for spawned agents (#785, length-capped by #387).
- *
- * Every agent used to inherit the host's `TMPDIR`/`TEMP`/`TMP` verbatim — they
- * ride in on `buildChildEnv`'s base allowlist — so every run on the machine
- * shared one directory. On a box that runs agents continuously and never
- * reboots, that directory is a tmpfs nobody reaps, and once it hits its quota
- * the failure is *silent*: the Claude Code CLI roots its scratch tree at
- * `os.tmpdir()` and round-trips each `Bash` command's stdout/stderr through a
- * file there. Under `EDQUOT` the inode is still allocated, so the file is
- * created and the write fails — the command runs, its side effects land, and
- * the agent reads back an empty result with a bogus exit status. Nothing in the
- * cockpit says anything is wrong.
- *
- * Three properties fix that, and this module owns all of them:
- *
- *   1. **Isolation** — each run gets `<dataDir>/tmp/<runId>`, on the same disk
- *      as the run's own state rather than a shared tmpfs, reaped when the run
- *      ends. `buildChildEnv` applies the per-run env last, so these values win
- *      over the host's without any allowlist change.
- *   2. **Fail loud** — the directory is write-probed before the backend spawns.
- *      A run that cannot get a working temp directory fails immediately with a
- *      named, actionable error instead of spawning an agent that will run blind.
- *   3. **Short enough to bind** (#387) — tools bind *named* unix sockets under
- *      `TMPDIR` (tsx's IPC server lays down `<tmpdir>/tsx-<uid>/<pid>.pipe`,
- *      Chrome a `SingletonSocket`), and the kernel caps a socket path at
- *      `sun_path` — 108 bytes on Linux, 104 on macOS, NUL included. A checkout
- *      deep enough (Cezar's own nested task worktrees land past 100 chars)
- *      pushed every such bind past the cap and broke `npm install` and
- *      typechecking inside the run. A directory that would land too deep
- *      resolves instead to a short digest-named directory under the OS temp
- *      root — still per-run, still probed, still reaped. A repo whose own path
- *      already fits keeps today's directory, byte for byte. When the ambient
- *      `TMPDIR` itself is too deep for that root's candidate (#440 — routine
- *      inside a cezar task session, whose `TMPDIR` is the checkout's own
- *      scratch tree per #785), the next root is the platform's own temp root
- *      (`/tmp`), which `TMPDIR` cannot deepen; only when no root fits does the
- *      spawn refuse.
- *
- * `CEZ_AGENT_TMPDIR=0` opts out of ALL THREE — cezar keeps its hands off the
- * temp directory entirely and the pre-#785 behaviour is back, byte for byte.
- * That is deliberate: an escape hatch that still imposed the preflight would be
- * a hatch you cannot actually escape through, and this repo's
- * graceful-degradation rule says a new check must never become the only way to
- * run.
+ * Task-owned temp directories with real-byte write probes and a Unix socket path budget. Prefer
+ * short repo-local paths; fall back to marked digest directories. CEZ_AGENT_TMPDIR=0 bypasses
+ * the mechanism.
  */
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { checkpointFallbackRemoval, fallbackIdentity, readFallbackRemovals } from './agent-tmpdir-removal.js';
 import { workerEvidenceRunIds } from './worker-execution.js';
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 /** Run ids are uuids; anything else must never reach a recursive `rmSync`.
@@ -59,28 +18,142 @@ import { basename, dirname, isAbsolute, join } from 'node:path';
 function safeRunId(id) {
     return /^[A-Za-z0-9._-]+$/.test(id) && id !== '.' && id !== '..';
 }
-/** Where a run's agent-scoped temp directory lives. */
+/**
+ * The run's CONTROL directory, `<dataDir>/tmp/<runId>`: it holds the recorded
+ * fallback location (`.cez-fallback`) and the partial-removal receipts, and its
+ * entries are what the startup sweep reads run ids from. Before
+ * hearsay-tools/cezarion#1022 it was also the TMPDIR handed to the agent; a
+ * directory minted then is still a location every holder scan, reap and sweep
+ * covers, and `agentTmpEnv` moves its contents to `agentShortTmpDir` on the
+ * run's next spawn.
+ */
 export function agentTmpDir(dataDir, runId) {
     return join(dataDir, 'tmp', runId);
 }
-/** The root every per-run directory hangs off — the ONLY tree this module
- *  removes anything from (`runs/`, `runs.json` and `worktrees/` are siblings). */
+/** The root every control directory hangs off (`runs/`, `runs.db` and
+ *  `worktrees/` are siblings this module never touches). */
 function agentTmpRoot(dataDir) {
     return join(dataDir, 'tmp');
 }
+const SHORT_TMP_ROOT = 't';
+const SHORT_TMP_NAME_LENGTH = 8;
+const RUN_FILE = '.cez-run';
+/**
+ * Repo-local scratch: <dataDir>/t/<id8>. The .cez-run marker names the full run; a foreign
+ * marker forces the OS-root fallback. Reap and sweep must respect that marker.
+ */
+export function agentShortTmpDir(dataDir, runId) {
+    return join(dataDir, SHORT_TMP_ROOT, runId.slice(0, SHORT_TMP_NAME_LENGTH));
+}
+/**
+ * Marker run id: null when absent, undefined when unreadable or malformed. Unknown ownership is
+ * retained. ENOTDIR is absent so spawn fails with AgentTempDirError when creation fails.
+ */
+function readRunMarker(dir) {
+    try {
+        const owner = readFileSync(join(dir, RUN_FILE), 'utf8');
+        return safeRunId(owner) && owner.slice(0, SHORT_TMP_NAME_LENGTH) === basename(dir) ? owner : undefined;
+    }
+    catch (err) {
+        const code = err.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? null : undefined;
+    }
+}
+function shortTmpDirClaim(dir, runId) {
+    const owner = readRunMarker(dir);
+    if (owner === null)
+        return 'free';
+    if (owner === undefined)
+        return 'unknown';
+    return owner === runId ? 'ours' : 'other';
+}
+/** Mint the `.cez-run` marker without ever following an existing name, and
+ *  refuse when the name turns out to be another run's — the read in
+ *  `resolveAgentTmpDir` already steered away from one, so this only fires on a
+ *  race or a replaced marker. The id is written to a private name first and
+ *  hard-linked into place: `link` publishes it whole or not at all and, like
+ *  `wx`, fails on an existing name, so a crash mid-write can never leave a
+ *  partial marker for the sweep to misread (hearsay-tools/cezarion#1037). */
+function writeRunMarker(dir, runId) {
+    const marker = join(dir, RUN_FILE);
+    const pending = `${marker}.${process.pid}.${randomUUID()}`;
+    writeFileSync(pending, runId, { encoding: 'utf8', flag: 'wx' });
+    try {
+        linkSync(pending, marker);
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        if (readRunMarker(dir) !== runId) {
+            throw new AgentTempDirError(dir, new Error('directory belongs to another run'));
+        }
+    }
+    finally {
+        unlinkSync(pending);
+    }
+}
+/**
+ * Carry a pre-hearsay-tools/cezarion#1022 run's scratch over to its new
+ * directory, so a Continue after the upgrade keeps its files (#515). Only a
+ * control directory that was the old TMPDIR qualifies — one holding a fallback
+ * pointer or removal receipt is control state and stays where the reap looks
+ * for it. Same filesystem (both under dataDir), so the rename is atomic; any
+ * failure just leaves a fresh directory, and the old one is still reaped.
+ */
+function adoptLegacyTmpDir(dataDir, runId, short) {
+    const legacy = agentTmpDir(dataDir, runId);
+    try {
+        if (existsSync(short) || !lstatSync(legacy).isDirectory())
+            return;
+        if (readdirSync(legacy).some((name) => name.startsWith('.cez-fallback')))
+            return;
+        mkdirSync(dirname(short), { recursive: true });
+        renameSync(legacy, short);
+    }
+    catch {
+        // best-effort: nothing to adopt, or it could not be moved.
+    }
+}
+/**
+ * The bytes Chromium appends to TMPDIR for its singleton socket —
+ * `/org.chromium.Chromium.XXXXXX/SingletonSocket`, 45 bytes (Google Chrome's
+ * `/com.google.Chrome.XXXXXX/...` is 41). The longest name any known tool lays
+ * down under TMPDIR: tsx's `/tsx-<uid>/<pid>.pipe` is ~22.
+ *
+ * Mirrors `CHROME_SINGLETON_OVERHEAD` in `.ai/scripts/resolve-browser-launch.mjs`,
+ * which the e2e seam applies to its own browser launches. The published
+ * package cannot import a repo script, so the value is written twice and
+ * `packages/cezar/test/unit/resolve-browser-launch.test.ts` asserts they agree.
+ */
+export const CHROME_SINGLETON_OVERHEAD = '/org.chromium.Chromium.XXXXXX/SingletonSocket'.length;
+/** `sockaddr_un.sun_path` on macOS, the tighter platform: 104 bytes, NUL
+ *  included (Linux has 108). Mirrors `DARWIN_UNIX_SOCKET_MAX` in
+ *  `.ai/scripts/resolve-browser-launch.mjs`, under the same agreement test. */
+export const DARWIN_UNIX_SOCKET_MAX = 103;
 /**
  * The longest a per-run temp directory may be so that tools binding named
  * unix sockets under it still work (#387), measured in UTF-8 bytes — the
- * kernel bounds the encoded path, not the JavaScript character count.
- * `sockaddr_un.sun_path` holds 108 bytes on Linux and 104 on macOS, NUL
- * included; the longest name a known tool lays down under TMPDIR is tsx's IPC
- * socket, `<tmpdir>/tsx-<uid>/<pid>.pipe`, ~22 bytes (Chrome's
- * `SingletonSocket` is 16). A 78-byte ceiling leaves ≥25 bytes of headroom on
- * the tighter platform — past anything these tools generate — while keeping
- * ordinary checkouts on their repo-local scratch: only a genuinely deep path,
- * like the 100-character directories #387 reports, moves to the fallback.
+ * kernel bounds the encoded path, not the JavaScript character count. It is
+ * the tighter platform's `sun_path` minus Chromium's singleton-socket suffix:
+ * 103 − 45 = 58. One value for every platform, so a checkout resolves the
+ * same way wherever it runs.
+ *
+ * It was 78 until hearsay-tools/cezarion#1022, sized for a `SingletonSocket`
+ * directly under TMPDIR. Chrome nests it one directory deeper, so a 77-byte
+ * task TMPDIR (an ordinary checkout's `.ai/cezar/tmp/<uuid>`) failed every
+ * browser launch with `Socket path too long`.
  */
-export const MAX_SOCKET_SAFE_DIR_LENGTH = 78;
+export const MAX_SOCKET_SAFE_DIR_LENGTH = DARWIN_UNIX_SOCKET_MAX - CHROME_SINGLETON_OVERHEAD;
+/** The pre-hearsay-tools/cezarion#1022 ceiling. Only reading a recorded fallback
+ *  pointer still accepts it: a run that recorded one under the old ceiling must
+ *  keep its scratch on Continue and must still be reaped, and the digest
+ *  equality check — not the length — is what validates the pointer. Such a
+ *  pointer is never handed to an agent again: `migrateLegacyFallback` moves its
+ *  scratch to a directory inside the new budget first. */
+const LEGACY_MAX_SOCKET_SAFE_DIR_LENGTH = 78;
+function fitsSocketBudget(path) {
+    return Buffer.byteLength(path, 'utf8') <= MAX_SOCKET_SAFE_DIR_LENGTH;
+}
 /** The OS temp root, symlink-resolved: `bind(2)` bounds the path the kernel
  *  walks, so the check must measure what the path resolves to, not what it
  *  says (macOS hands out `/var/folders/...` through a `/private/var` symlink). */
@@ -126,6 +199,11 @@ const FALLBACK_NAME_LENGTH = 12;
  *  without this marker a sweep could not tell its own stale directories from
  *  another project's live ones in the shared root — and would delete them. */
 const OWNER_FILE = '.cez-owner';
+/** The dataDir itself, beside the marker (hearsay-tools/cezarion#1911). The digest cannot
+ *  name a dataDir that was deleted, so without this path no sweep could ever match that
+ *  dataDir's fallback directories again. It is a claim, not proof: the sweep trusts it only
+ *  when it digests to the marker. */
+const OWNER_DIR_FILE = '.cez-owner-dir';
 function dataDirOwner(dataDir) {
     return createHash('sha256').update(`cez-agent-owner:${dataDir}`).digest('hex').slice(0, 16);
 }
@@ -156,6 +234,36 @@ function writeOwnerMarker(dir, dataDir) {
             throw new AgentTempDirError(dir, new Error('ownership marker was replaced — remove the directory to re-mint it'));
         }
     }
+    // A directory minted before this file existed gets it on its next spawn. An existing one is
+    // left as it is: the sweep checks it against the marker before it acts on it.
+    try {
+        writeFileSync(join(dir, OWNER_DIR_FILE), dataDir, { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+}
+/** True only when the fallback's recorded dataDir digests to its marker `owner` and that
+ *  dataDir no longer exists. A missing or mismatched record, or any error but ENOENT, keeps
+ *  the directory. */
+function ownerDataDirGone(dir, owner) {
+    let dataDir;
+    try {
+        dataDir = readFileSync(join(dir, OWNER_DIR_FILE), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (!isAbsolute(dataDir) || dataDirOwner(dataDir) !== owner)
+        return false;
+    try {
+        lstatSync(dataDir);
+        return false;
+    }
+    catch (err) {
+        return err.code === 'ENOENT';
+    }
 }
 /**
  * Where the fallback lives for this dataDir+run pair under one root. The name
@@ -176,8 +284,14 @@ function fallbackTmpDir(root, dataDir, runId) {
  * host temp environment can change between sessions, so recomputing it loses
  * the task's files. Only a digest-named absolute path is accepted on read. */
 const LOCATION_FILE = '.cez-fallback';
-function recordedFallback(dataDir, runId) {
-    const marker = join(agentTmpDir(dataDir, runId), LOCATION_FILE);
+/** The location a pointer migration is moving scratch AWAY from
+ *  (hearsay-tools/cezarion#1037). It exists only between rewriting
+ *  `.cez-fallback` and finishing the move, so a crash in that window still
+ *  leaves the old directory in every holder scan, reap and sweep — the old root
+ *  may be one no later env lists. */
+const PREVIOUS_LOCATION_FILE = '.cez-fallback-previous';
+function recordedFallback(dataDir, runId, file = LOCATION_FILE) {
+    const marker = join(agentTmpDir(dataDir, runId), file);
     let dir;
     try {
         dir = readFileSync(marker, 'utf8');
@@ -188,11 +302,83 @@ function recordedFallback(dataDir, runId) {
         throw new AgentTempDirError(marker, err);
     }
     if (!isAbsolute(dir) || dir !== fallbackTmpDir(dirname(dir), dataDir, runId)
-        || Buffer.byteLength(dir, 'utf8') > MAX_SOCKET_SAFE_DIR_LENGTH) {
+        || Buffer.byteLength(dir, 'utf8') > LEGACY_MAX_SOCKET_SAFE_DIR_LENGTH) {
         throw new AgentTempDirError(marker, new Error('invalid recorded fallback directory'));
     }
     return dir;
 }
+/** Replace a location record whole: write a private name, then `rename` over
+ *  the record, so a crash leaves the old pointer or the new one, never a torn
+ *  one. The private name never follows an existing file (`wx`). */
+function rewriteLocation(dataDir, runId, file, dir) {
+    const target = join(agentTmpDir(dataDir, runId), file);
+    const pending = `${target}.${randomUUID()}.tmp`;
+    writeFileSync(pending, dir, { encoding: 'utf8', flag: 'wx' });
+    try {
+        renameSync(pending, target);
+    }
+    finally {
+        rmSync(pending, { force: true });
+    }
+}
+/**
+ * Move the scratch of a fallback recorded under the pre-hearsay-tools/cezarion#1022
+ * ceiling to `dir`, the socket-safe directory resolution now picks
+ * (hearsay-tools/cezarion#1037). Handing the old path back would keep a 59–78
+ * byte TMPDIR that Chromium's nested singleton socket cannot bind under.
+ *
+ * Order is what makes a crash safe, and every re-run converges:
+ *   1. record the old location in `.cez-fallback-previous`, so it stays in
+ *      scans and reaps whatever the env is later;
+ *   2. point `.cez-fallback` at `dir`;
+ *   3. move the files — `rename` when `dir` does not exist yet, otherwise (or on
+ *      `EXDEV`, the usual case across temp roots) copy into `dir` and remove the
+ *      old directory under a removal receipt, so a removal cut short after the
+ *      owner marker went still proves the directory ours on retry;
+ *   4. drop `.cez-fallback-previous`.
+ * The old directory is moved only when its `.cez-owner` marker is this
+ * dataDir's (or a receipt proves it was); anything else refuses the spawn.
+ */
+function migrateLegacyFallback(dataDir, runId, dir) {
+    const recorded = recordedFallback(dataDir, runId);
+    const from = recordedFallback(dataDir, runId, PREVIOUS_LOCATION_FILE)
+        ?? (recorded !== undefined && recorded !== dir ? recorded : undefined);
+    if (from === undefined)
+        return;
+    const local = agentTmpDir(dataDir, runId);
+    if (from !== dir) {
+        rewriteLocation(dataDir, runId, PREVIOUS_LOCATION_FILE, from);
+        if (recorded !== dir)
+            rewriteLocation(dataDir, runId, LOCATION_FILE, dir);
+        const removals = readFallbackRemovals(local);
+        if (!fallbackOwnedOrAbsent(dataDir, from, removals)) {
+            throw new AgentTempDirError(from, new Error('ownership marker was replaced — remove the directory to re-mint it'));
+        }
+        if (existsSync(from))
+            moveFallbackScratch(dataDir, local, from, dir, removals);
+    }
+    rmSync(join(local, PREVIOUS_LOCATION_FILE), { force: true });
+}
+function moveFallbackScratch(dataDir, local, from, to, removals) {
+    if (!existsSync(to)) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (err) {
+            if (err.code !== 'EXDEV')
+                throw err;
+        }
+    }
+    mkdirSync(to, { recursive: true, mode: 0o700 });
+    // The destination keeps (or gets) its own marker; the source's is never
+    // copied over it, so a foreign marker still refuses instead of being replaced.
+    writeOwnerMarker(to, dataDir);
+    const markers = new Set([join(from, OWNER_FILE), join(from, OWNER_DIR_FILE)]);
+    cpSync(from, to, { recursive: true, force: true, verbatimSymlinks: true, preserveTimestamps: true, filter: (src) => !markers.has(src) });
+    checkpointFallbackRemoval(local, from, removals);
+    rmSync(from, { recursive: true, force: true });
+}
 function recordFallback(dataDir, runId, dir) {
     const local = agentTmpDir(dataDir, runId);
     mkdirSync(local, { recursive: true });
@@ -212,28 +398,43 @@ function recordFallback(dataDir, runId, dir) {
  *  with the real candidates, tests with synthetic ones, so the nothing-fits
  *  branch stays exercised even though a real platform root is always short. */
 export function firstSocketSafeDir(paths) {
-    return paths.find((path) => Buffer.byteLength(path, 'utf8') <= MAX_SOCKET_SAFE_DIR_LENGTH);
+    return paths.find(fitsSocketBudget);
 }
 /**
- * The temp directory this run should use: the repo-local per-run directory
- * when it is short enough for unix-socket paths, and otherwise a short
+ * The temp directory this run should use: the repo-local `agentShortTmpDir`
+ * when it is short enough for unix-socket paths and no other run's marker
+ * claims it, and otherwise a short
  * digest-named directory under the first OS temp root whose candidate fits —
  * the env-honouring root first, the platform default when `TMPDIR` itself is
- * too deep (#387, #440). A recorded location wins across host-env changes.
+ * too deep (#387, #440). A recorded location wins across host-env changes
+ * while it fits the budget; one recorded under the pre-#1022 ceiling resolves
+ * to the fallback that fits now, where `agentTmpEnv` moves its scratch.
  * Read-only resolution — nothing is created, nothing is
  * probed; `agentTmpEnv` owns the side effects.
  */
 export function resolveAgentTmpDir(dataDir, runId) {
     const recorded = recordedFallback(dataDir, runId);
-    if (recorded)
+    // A pointer recorded under the pre-#1022 ceiling is not reused: resolution
+    // picks a fallback that fits, and `agentTmpEnv` moves the scratch there.
+    if (recorded && fitsSocketBudget(recorded))
         return recorded;
-    const local = agentTmpDir(dataDir, runId);
-    if (Buffer.byteLength(local, 'utf8') <= MAX_SOCKET_SAFE_DIR_LENGTH)
-        return local;
+    // An id that is not a plain identifier never names a repo-local directory;
+    // the digest-named fallback is safe for any input.
+    const local = safeRunId(runId) ? agentShortTmpDir(dataDir, runId) : agentTmpDir(dataDir, runId);
+    // A legacy pointer's scratch moves to another fallback, never into the
+    // repo-local directory: the control directory keeps owning its location.
+    if (!recorded && safeRunId(runId) && fitsSocketBudget(local)) {
+        const claim = shortTmpDirClaim(local, runId);
+        if (claim === 'free' || claim === 'ours')
+            return local;
+    }
     const candidates = osTempRoots().map((root) => fallbackTmpDir(root, dataDir, runId));
     const fallback = firstSocketSafeDir(candidates);
     if (fallback)
         return fallback;
+    if (recorded) {
+        throw new AgentTempDirError(recorded, new Error(`recorded fallback is past the ${MAX_SOCKET_SAFE_DIR_LENGTH}-byte unix socket budget and no OS temp root has a candidate that fits`));
+    }
     // Nothing fits — every root, the platform default included, has a candidate
     // past the cap. Minting any would hand the agent a temp directory that
     // cannot serve unix sockets: the silent failure #387 is about. Fail the
@@ -271,7 +472,7 @@ export class AgentTempDirError extends Error {
     }
 }
 /** Opt-out spelling matches the house style for default-on behaviour
- *  (`CEZ_AUTONAME=0`, `CEZ_SKILLS_AUTO_UPDATE=0`): only an exact `0` disables. */
+ *  (`CEZ_AUTONAME=0`): only an exact `0` disables. */
 export function agentTmpDirEnabled(env = process.env) {
     return env.CEZ_AGENT_TMPDIR !== '0';
 }
@@ -279,10 +480,8 @@ export function agentTmpDirEnabled(env = process.env) {
  *  spawns racing on the same directory delete each other's file mid-probe. */
 let probeSeq = 0;
 /**
- * Write-probe `dir`. Creating the file is not enough to prove the directory
- * works — a quota-exhausted tmpfs still allocates the inode and only fails the
- * `write(2)` — so the probe writes real bytes and removes them again. A
- * directory that is merely *full but writable* passes, by design.
+ * Probe with a real data write, then remove the probe. File creation alone does not prove writes
+ * work.
  */
 function probeWritable(dir) {
     const probe = join(dir, `.cez-tmp-probe-${process.pid}-${(probeSeq += 1)}`);
@@ -324,19 +523,27 @@ function probeWritable(dir) {
 export function agentTmpEnv(dataDir, runId, env = process.env) {
     if (!agentTmpDirEnabled(env))
         return {};
-    const local = agentTmpDir(dataDir, runId);
     const dir = resolveAgentTmpDir(dataDir, runId);
+    const repoLocal = safeRunId(runId) && dir === agentShortTmpDir(dataDir, runId);
     try {
-        mkdirSync(dir, dir === local ? { recursive: true } : { recursive: true, mode: 0o700 });
-        // In the shared OS root the directory carries its ownership marker, so a
-        // startup sweep from another project can tell it apart from stale
-        // scratch (the sweep skips anything whose marker is missing or foreign).
-        if (dir !== local) {
+        if (repoLocal) {
+            adoptLegacyTmpDir(dataDir, runId, dir);
+            mkdirSync(dir, { recursive: true });
+            writeRunMarker(dir, runId);
+        }
+        else {
+            // In the shared OS root the directory carries its ownership marker, so a
+            // startup sweep from another project can tell it apart from stale
+            // scratch (the sweep skips anything whose marker is missing or foreign).
+            migrateLegacyFallback(dataDir, runId, dir);
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
             writeOwnerMarker(dir, dataDir);
             recordFallback(dataDir, runId, dir);
         }
     }
     catch (err) {
+        if (err instanceof AgentTempDirError)
+            throw err;
         throw new AgentTempDirError(dir, err);
     }
     probeWritable(dir);
@@ -347,13 +554,15 @@ export function agentTmpEnv(dataDir, runId, env = process.env) {
 function fallbackLocations(dataDir, runId) {
     const paths = new Set(osTempRoots().map(root => fallbackTmpDir(root, dataDir, runId)));
     let complete = true, removals = [];
-    try {
-        const recorded = recordedFallback(dataDir, runId);
-        if (recorded)
-            paths.add(recorded);
-    }
-    catch {
-        complete = false;
+    for (const file of [LOCATION_FILE, PREVIOUS_LOCATION_FILE]) {
+        try {
+            const recorded = recordedFallback(dataDir, runId, file);
+            if (recorded)
+                paths.add(recorded);
+        }
+        catch {
+            complete = false;
+        }
     }
     // Independent evidence: a damaged receipt must never discard a readable pointer (#738).
     try {
@@ -400,7 +609,8 @@ export function agentTmpDirOwnershipProven(dataDir, runId) {
         return false;
     try {
         const { paths, removals, complete } = fallbackLocations(dataDir, runId);
-        return complete && paths.every(path => fallbackOwnedOrAbsent(dataDir, path, removals));
+        return complete && shortTmpDirClaim(agentShortTmpDir(dataDir, runId), runId) !== 'unknown'
+            && paths.every(path => fallbackOwnedOrAbsent(dataDir, path, removals));
     }
     catch {
         return false;
@@ -416,7 +626,11 @@ export function agentTmpDirLocationEvidence(dataDir, runId) {
     if (!safeRunId(runId))
         return { paths: [], complete: false };
     const { paths, complete } = fallbackLocations(dataDir, runId);
-    return { paths: [agentTmpDir(dataDir, runId), ...paths], complete };
+    // The short directory is listed unless its marker positively names another
+    // run: an unreadable marker is uncertainty, and uncertainty stays in scans.
+    const short = agentShortTmpDir(dataDir, runId);
+    const shorts = shortTmpDirClaim(short, runId) === 'other' ? [] : [short];
+    return { paths: [agentTmpDir(dataDir, runId), ...shorts, ...paths], complete };
 }
 /** Only ENOENT proves cleanup finished. Permission/read errors retain the durable intent. */
 export function agentTmpDirMayExist(dataDir, runId) {
@@ -433,17 +647,18 @@ export function agentTmpDirMayExist(dataDir, runId) {
     });
 }
 /**
- * Reap one task's directory after terminal completion or history deletion.
- * Session close alone is not completion: a live task's Continue must retain
- * its files. Never throws — reaping must not break a terminal transition.
- *
- * The repo-local directory and the digest name under EVERY root are tried,
- * because the resolution depends on the lengths of `dataDir` and the ambient
- * `TMPDIR`, either of which a Continue, a re-base or a changed env can move
- * between mint and reap; removing a name that was never minted is a no-op, so
- * trying them all is pure safety.
+ * Reap scratch after terminal completion or history deletion, never session close alone. Try
+ * repo-local paths and every digest root, subject to ownership checks. Never throw from cleanup.
  */
 export function removeAgentTmpDir(dataDir, runId) {
+    reapAgentTmpDir(dataDir, runId, false);
+}
+/** `spareUnclaimedShort` keeps a markerless short directory: the startup sweep
+ *  sets it when a kept run's `agentShortTmpDir` lands on the same name, because
+ *  that run may have created or adopted the directory and crashed before
+ *  publishing its marker (hearsay-tools/cezarion#1037) — it is that run's
+ *  Continue scratch, not this orphan's. */
+function reapAgentTmpDir(dataDir, runId, spareUnclaimedShort) {
     if (!safeRunId(runId))
         return;
     const local = agentTmpDir(dataDir, runId);
@@ -472,6 +687,14 @@ export function removeAgentTmpDir(dataDir, runId) {
                     throw error;
             }
         }
+        // The short directory goes only when it is this run's (or unclaimed): a
+        // colliding name may be another run's live scratch.
+        const short = agentShortTmpDir(dataDir, runId);
+        const claim = shortTmpDirClaim(short, runId);
+        if (claim === 'unknown')
+            return;
+        if (claim === 'ours' || (claim === 'free' && !spareUnclaimedShort))
+            rmSync(short, { recursive: true, force: true });
         // The durable location and partial-removal receipts are last, never before a fallback.
         rmSync(local, { recursive: true, force: true });
     }
@@ -480,19 +703,8 @@ export function removeAgentTmpDir(dataDir, runId) {
     }
 }
 /**
- * Remove every per-run directory that is not in `keepRunIds` — the startup
- * sweep, so a crash (which never reaches the terminal-transition reap) cannot
- * accumulate them forever. Three confined sets are swept and nothing else:
- *
- *   - `<dataDir>/tmp`, where entries ARE the run ids (reports the ids reaped);
- *   - the `cez-agent-<12 hex>` directories under EVERY OS temp root — the
- *     env-honouring root and the platform default (#440) — where the name
- *     digests the dataDir and is not reversible to a run id (reports the
- *     directory names reaped). The pattern is exact — prefix, lowercase hex,
- *     fixed length, directories only — and a directory is removed only when
- *     its `.cez-owner` marker names THIS dataDir and none of this dataDir's
- *     kept runs claims it, so another project's scratch in a shared root is
- *     never touched.
+ * Startup sweep of confined repo-local and digest directories not claimed by keepRunIds. Respect
+ * full-run and dataDir ownership markers; retain unreadable or uncertain ownership.
  */
 export function sweepAgentTmpDirs(dataDir, keepRunIds) {
     // Private worker evidence outlives corrupt/missing/quarantined index rows. Both local
@@ -503,6 +715,9 @@ export function sweepAgentTmpDirs(dataDir, keepRunIds) {
     const keep = new Set([...keepRunIds, ...workers]);
     const reaped = [];
     let entries;
+    // Short names a kept run resolves to. Computed before the legacy loop, which
+    // must spare them too: a markerless one is a kept run's, mid-mint.
+    const claimedShort = new Set([...keep].filter(safeRunId).map((id) => basename(agentShortTmpDir(dataDir, id))));
     const root = agentTmpRoot(dataDir);
     if (existsSync(root)) {
         try {
@@ -518,7 +733,7 @@ export function sweepAgentTmpDirs(dataDir, keepRunIds) {
                 continue;
             try {
                 const locations = agentTmpDirLocations(dataDir, name).filter(dir => existsSync(dir));
-                removeAgentTmpDir(dataDir, name);
+                reapAgentTmpDir(dataDir, name, claimedShort.has(basename(agentShortTmpDir(dataDir, name))));
                 reaped.push(...locations.filter(dir => !existsSync(dir)).map(dir => basename(dir)));
             }
             catch {
@@ -526,14 +741,55 @@ export function sweepAgentTmpDirs(dataDir, keepRunIds) {
             }
         }
     }
-    // The #387 fallback locations, in every shared OS temp root. Kept narrow on
-    // purpose: exact prefix, 12 lowercase-hex name, directories only, and
-    // ownership — a directory is removed only when its `.cez-owner` marker
-    // names THIS dataDir (a marker that is missing or foreign is another
-    // project's, or unknown, and is never ours to remove) and none of this
-    // dataDir's kept runs claims it.
+    // The hearsay-tools/cezarion#1022 short directories. Every entry here is this
+    // dataDir's own, so no ownership marker is needed — only the claim check
+    // that keeps a kept run's directory, and a colliding name's, alive.
+    const shortRoot = join(dataDir, SHORT_TMP_ROOT);
+    if (existsSync(shortRoot)) {
+        let shortEntries;
+        try {
+            shortEntries = readdirSync(shortRoot, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        }
+        catch {
+            shortEntries = [];
+        }
+        for (const name of shortEntries) {
+            if (!safeRunId(name))
+                continue;
+            const owner = readRunMarker(join(shortRoot, name));
+            if (owner === undefined)
+                continue; // unreadable marker: unknown ownership is never ours to remove.
+            // A marker that is a proper prefix of a kept run's id is that run's, cut short.
+            if (owner === null ? claimedShort.has(name) : [...keep].some((id) => id.startsWith(owner)))
+                continue;
+            try {
+                rmSync(join(shortRoot, name), { recursive: true, force: true });
+                reaped.push(owner ?? name);
+            }
+            catch {
+                // best-effort: a locked directory is retried on the next boot.
+            }
+        }
+    }
+    reaped.push(...sweepFallbackRoots(dataDir, keep));
+    return reaped;
+}
+/**
+ * The #387 fallback locations, in every shared OS temp root. Kept narrow on
+ * purpose: exact prefix, 12 lowercase-hex name, directories only, and
+ * ownership — a directory is removed only when its `.cez-owner` marker
+ * names THIS dataDir and none of this dataDir's kept runs claims it, or
+ * when its marker names a dataDir that no longer exists
+ * (hearsay-tools/cezarion#1911): nothing else will ever remove that one. A
+ * marker that is missing, unreadable or names a live dataDir is another
+ * project's, or unknown, and is never ours to remove.
+ */
+function sweepFallbackRoots(dataDir, keep) {
     const owner = dataDirOwner(dataDir);
     const claimed = new Set([...keep].filter(safeRunId).map((id) => basename(fallbackTmpDir(osTempRoot(), dataDir, id))));
+    const reaped = [];
     for (const osRoot of osTempRoots()) {
         let fallbackEntries;
         try {
@@ -543,20 +799,7 @@ export function sweepAgentTmpDirs(dataDir, keepRunIds) {
             continue; // an unreadable root is skipped, not fatal: others remain.
         }
         for (const entry of fallbackEntries) {
-            if (!entry.isDirectory() || !entry.name.startsWith(FALLBACK_PREFIX))
-                continue;
-            if (!/^[0-9a-f]{12}$/.test(entry.name.slice(FALLBACK_PREFIX.length)))
-                continue;
-            let entryOwner;
-            try {
-                entryOwner = readFileSync(join(osRoot, entry.name, OWNER_FILE), 'utf8').trim();
-            }
-            catch {
-                continue; // no readable marker: unknown ownership is never ours to remove.
-            }
-            if (entryOwner !== owner)
-                continue;
-            if (claimed.has(entry.name))
+            if (!fallbackSweepable(osRoot, entry, owner, claimed))
                 continue;
             try {
                 rmSync(join(osRoot, entry.name), { recursive: true, force: true });
@@ -569,4 +812,18 @@ export function sweepAgentTmpDirs(dataDir, keepRunIds) {
     }
     return reaped;
 }
+function fallbackSweepable(osRoot, entry, owner, claimed) {
+    if (!entry.isDirectory() || !entry.name.startsWith(FALLBACK_PREFIX))
+        return false;
+    if (!/^[0-9a-f]{12}$/.test(entry.name.slice(FALLBACK_PREFIX.length)))
+        return false;
+    let entryOwner;
+    try {
+        entryOwner = readFileSync(join(osRoot, entry.name, OWNER_FILE), 'utf8').trim();
+    }
+    catch {
+        return false; // no readable marker: unknown ownership is never ours to remove.
+    }
+    return entryOwner === owner ? !claimed.has(entry.name) : ownerDataDirGone(join(osRoot, entry.name), entryOwner);
+}
 //# sourceMappingURL=agent-tmpdir.js.map