@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/install.js

@@ -1,15 +1,28 @@
 // `oars sessions hook install|uninstall|status`: writes the four Claude Code hook entries into one settings file, merging with what is
 // there. An entry is ours when its command ends with `hook-bin.js" <session-start|pre-tool|post-tool|stop>`, so uninstall removes those entries and nothing else. Also the retention floor
-// (the harness deletes raw transcripts after `cleanupPeriodDays`, 30 when unset) and the Windows nightly task.
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+// (the harness deletes raw transcripts after `cleanupPeriodDays`, 30 when unset) and removing the Windows task earlier versions registered.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { CliError, ExitCode } from '../errors.js';
 import { ACTION_TABLES } from './actions.js';
+import { writeOwnerOnly } from './owner-only.js';
 export const RETENTION_FLOOR = 365;
 export const DEFAULT_RETENTION = 30;
 export const TASK_NAME = 'OarsSessionsNightly';
 // The tail of a command this module wrote; anything else in a settings file is the operator's, whatever it is called.
-const OWN_COMMAND = /hook-bin\.js" (?:session-start|prompt|pre-tool|post-tool|stop)$/;
+// The machine command is host-independent: it names no install path, only the `oars-hook` bin on PATH (see `MACHINE_COMMAND`).
+// A plain install and a machine install each replace only their own entries, so one never strips the other's; uninstall and status read both.
+const PLAIN_COMMAND = /hook-bin\.js" (?:session-start|prompt|pre-tool|post-tool|stop)$/;
+const MACHINE_OWN = /oars-hook stop --machine$/;
+const OWN_COMMAND = /(?:hook-bin\.js" (?:session-start|prompt|pre-tool|post-tool|stop)|oars-hook stop --machine)$/;
+/**
+ * What `--machine` writes for Stop and SessionEnd. A settings file committed from one machine is read on another (a cloud VM, a runner), where the installing machine's node and `hook-bin.js` paths do not exist, so this names no path:
+ * it resolves the `oars-hook` bin on PATH, and exits 0 when there is none (a hook that cannot start must not fail the session).
+ */
+export const MACHINE_COMMAND = 'command -v oars-hook >/dev/null || exit 0; oars-hook stop --machine';
+const MACHINE_EVENTS = ['Stop', 'SessionEnd'];
+// The hook body is a node start and a detach (well under a second); this is the harness's ceiling, not its budget.
+const MACHINE_TIMEOUT = 10;
 const SPECS = [
     { event: 'SessionStart', arg: 'session-start', timeout: 5 },
     // The split-positions table again, only when it changed since this session's last one (`hooks.ts`); a prompt with nothing new costs one node start and prints nothing.
@@ -35,15 +48,15 @@ export const commandOf = (runtime, arg) => {
         return `${present}${launch}`;
     return `${present}IFS= read -r event; case "$event" in '') exit 0;; *'"tool_name":"Bash"'*|*'"tool_name":"PowerShell"'*) case "$event" in *'Exit code'*) ;; *) exit 0;; esac;; esac; { printf '%s\\n' "$event"; cat; } | ${launch}`;
 };
-const isOwnHook = (hook) => isObject(hook) && typeof hook.command === 'string' && OWN_COMMAND.test(hook.command);
-/** The groups with our entries taken out; a group that held only ours goes, one that held others keeps them. */
-const withoutOwn = (groups) => groups.flatMap((group) => {
-    if (!isObject(group) || !Array.isArray(group.hooks) || !group.hooks.some(isOwnHook))
+const isOwnHook = (hook, own) => isObject(hook) && typeof hook.command === 'string' && own.test(hook.command);
+/** The groups with our entries taken out; a group that held only ours goes, one that held others keeps them. `own` tells ours by the command's tail. */
+export const withoutOwn = (groups, own = OWN_COMMAND) => groups.flatMap((group) => {
+    if (!isObject(group) || !Array.isArray(group.hooks) || !group.hooks.some((hook) => isOwnHook(hook, own)))
         return [group];
-    const rest = group.hooks.filter((hook) => !isOwnHook(hook));
+    const rest = group.hooks.filter((hook) => !isOwnHook(hook, own));
     return rest.length === 0 ? [] : [{ ...group, hooks: rest }];
 });
-const hasOwn = (groups) => groups.some((group) => isObject(group) && Array.isArray(group.hooks) && group.hooks.some(isOwnHook));
+export const hasOwn = (groups, own = OWN_COMMAND) => groups.some((group) => isObject(group) && Array.isArray(group.hooks) && group.hooks.some((hook) => isOwnHook(hook, own)));
 export const settingsPath = (runtime, scope, file) => {
     if (scope === 'user')
         return runtime.userSettings;
@@ -77,12 +90,12 @@ export const readSettings = async (path) => {
         throw new CliError(`${path} is not a JSON object; nothing was changed.`, ExitCode.USAGE, 'usage');
     return parsed;
 };
-const writeSettings = async (path, settings) => {
+export const writeSettings = async (path, settings) => {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
 };
-const hooksOf = (settings) => (isObject(settings.hooks) ? settings.hooks : {});
-const groupsOf = (hooks, event) => {
+export const hooksOf = (settings) => (isObject(settings.hooks) ? settings.hooks : {});
+export const groupsOf = (hooks, event) => {
     const groups = hooks[event];
     return Array.isArray(groups) ? groups : [];
 };
@@ -91,11 +104,11 @@ export const effectiveRetention = (settings) => (typeof settings.cleanupPeriodDa
 /** Events an earlier build registered our entries under; install and uninstall clear them so a stale entry cannot keep running. */
 const LEGACY_EVENTS = ['Stop'];
 /** Takes our entries out of `event`, dropping the key when that empties it. */
-const clearLegacy = (hooks, event) => {
+const clearLegacy = (hooks, event, own) => {
     const groups = groupsOf(hooks, event);
-    if (!hasOwn(groups))
+    if (!hasOwn(groups, own))
         return false;
-    const kept = withoutOwn(groups);
+    const kept = withoutOwn(groups, own);
     if (kept.length === 0)
         Reflect.deleteProperty(hooks, event);
     else
@@ -106,9 +119,9 @@ export const installHooks = async (runtime, path, keepRetention) => {
     const settings = await readSettings(path);
     const hooks = hooksOf(settings);
     for (const event of LEGACY_EVENTS)
-        clearLegacy(hooks, event);
+        clearLegacy(hooks, event, PLAIN_COMMAND);
     for (const spec of SPECS) {
-        const others = withoutOwn(groupsOf(hooks, spec.event));
+        const others = withoutOwn(groupsOf(hooks, spec.event), PLAIN_COMMAND);
         const entry = { type: 'command', command: commandOf(runtime, spec.arg), timeout: spec.timeout };
         hooks[spec.event] = [...others, spec.matcher === undefined ? { hooks: [entry] } : { matcher: spec.matcher, hooks: [entry] }];
     }
@@ -139,11 +152,38 @@ export const installHooks = async (runtime, path, keepRetention) => {
     await writeSettings(path, settings);
     return { file: path, installed: SPECS.map((spec) => spec.event), retention };
 };
+/**
+ * `hook install --machine`: the Stop and SessionEnd entries that run `oars-hook stop --machine`, merged with what is there (only entries of ours are replaced). With `env`, the enrollment block goes to this file's `env`
+ * block, merged with the operator's own entries, and the file is made owner-only, because it then holds the salts and the terms. A project file gets no `env`: it is committed.
+ */
+export const installMachineHooks = async (path, env) => {
+    const settings = await readSettings(path);
+    const hooks = hooksOf(settings);
+    for (const event of MACHINE_EVENTS) {
+        hooks[event] = [...withoutOwn(groupsOf(hooks, event), MACHINE_OWN), { hooks: [{ type: 'command', command: MACHINE_COMMAND, timeout: MACHINE_TIMEOUT }] }];
+    }
+    settings.hooks = hooks;
+    if (env === undefined) {
+        await writeSettings(path, settings);
+    }
+    else {
+        const merged = { ...(isObject(settings.env) ? settings.env : {}), ...env };
+        // The terms are given once: a re-install that names one variable replaces the other. A Stop lets the inline list win, so an earlier one would silently outlive the new list and keep terms in a file the operator moved them out of.
+        if (env.OARS_EXCLUSION_TERMS !== undefined)
+            Reflect.deleteProperty(merged, 'OARS_EXCLUSION_TERMS_INLINE');
+        if (env.OARS_EXCLUSION_TERMS_INLINE !== undefined)
+            Reflect.deleteProperty(merged, 'OARS_EXCLUSION_TERMS');
+        settings.env = merged;
+        await mkdir(dirname(path), { recursive: true });
+        await writeOwnerOnly(path, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+    return { file: path, installed: [...MACHINE_EVENTS], retention: 'Left cleanupPeriodDays alone: a machine builds its batch at each Stop, not from a stored transcript.' };
+};
 export const uninstallHooks = async (path) => {
     const settings = await readSettings(path);
     const hooks = hooksOf(settings);
     const removed = [];
-    const cleared = LEGACY_EVENTS.map((event) => clearLegacy(hooks, event)).includes(true);
+    const cleared = LEGACY_EVENTS.map((event) => clearLegacy(hooks, event, OWN_COMMAND)).includes(true);
     for (const spec of SPECS) {
         const groups = groupsOf(hooks, spec.event);
         if (!hasOwn(groups))
@@ -152,7 +192,10 @@ export const uninstallHooks = async (path) => {
         removed.push(spec.event);
         hooks[spec.event] = kept;
     }
-    if (removed.length > 0 || cleared) {
+    // Stop is no spec's event: a machine install writes it, and an earlier build did.
+    if (cleared)
+        removed.push('Stop');
+    if (removed.length > 0) {
         // An event this call emptied goes; an event that was already an empty list in the file is the operator's and stays.
         const remaining = Object.entries(hooks).filter(([event, groups]) => !(removed.includes(event) && Array.isArray(groups) && groups.length === 0));
         // `undefined` is left out of the JSON, so an emptied `hooks` key goes.
@@ -171,76 +214,31 @@ export const hookStatus = async (runtime, extra) => {
     for (const target of targets) {
         const settings = await readSettings(target.file);
         const hooks = hooksOf(settings);
-        statuses.push({ ...target, installed: SPECS.filter((spec) => hasOwn(groupsOf(hooks, spec.event))).map((spec) => spec.event), retentionDays: effectiveRetention(settings) });
+        statuses.push({ ...target, installed: [...SPECS.filter((spec) => hasOwn(groupsOf(hooks, spec.event))).map((spec) => spec.event), ...LEGACY_EVENTS.filter((event) => hasOwn(groupsOf(hooks, event)))], retentionDays: effectiveRetention(settings) });
     }
     return statuses;
 };
-/** The `schtasks` arguments for the nightly task: the same node and hook-bin the hooks use, at a fixed hour. */
-export const scheduleArgs = (runtime, hour) => [
-    '/Create',
-    '/TN',
-    TASK_NAME,
-    '/TR',
-    `"${runtime.nodePath}" "${runtime.hookBin}" nightly`,
-    '/SC',
-    'DAILY',
-    '/ST',
-    `${String(hour).padStart(2, '0')}:00`,
-    '/F',
-];
-export const SCHEDULE_HOUR = 3;
-const registered = () => `Scheduled task ${TASK_NAME}: the full deposit and the recurrence refresh run daily at ${String(SCHEDULE_HOUR).padStart(2, '0')}:00.`;
-export const setSchedule = async (runtime, mode) => {
-    if (mode === 'nightly') {
-        const created = await runtime.schtasks(scheduleArgs(runtime, SCHEDULE_HOUR));
-        if (created.code !== 0)
-            throw new CliError(`Could not register the scheduled task: ${created.output.trim()}`, ExitCode.UNEXPECTED, 'unexpected');
-        return registered();
-    }
-    const deleted = await runtime.schtasks(['/Delete', '/TN', TASK_NAME, '/F']);
-    return deleted.code === 0 ? `Removed the scheduled task ${TASK_NAME}.` : `No scheduled task ${TASK_NAME} to remove.`;
-};
-/** Where `--schedule off` is remembered: a file of its own in the sessions store, because `state.json` is rewritten whole by every deposit. */
-const scheduleRecord = (storeDir) => join(storeDir, 'schedule.json');
-/** True once the operator ran `--schedule off` and has not run `--schedule nightly` since. A record that cannot be read or parsed counts as no opt-out. */
-export const scheduleOptedOut = async (storeDir) => {
-    try {
-        const parsed = JSON.parse(await readFile(scheduleRecord(storeDir), 'utf8'));
-        return typeof parsed === 'object' && parsed !== null && 'schedule' in parsed && parsed.schedule === 'off';
-    }
-    catch {
-        return false;
-    }
-};
-/** Records the choice of `--schedule`: `off` writes the opt-out; `nightly` clears it. Without a store the choice has nowhere to live and is not recorded. */
-export const recordSchedule = async (storeDir, mode) => {
-    if (storeDir === undefined)
-        return;
-    if (mode === 'nightly') {
-        await rm(scheduleRecord(storeDir), { force: true });
-        return;
-    }
-    await mkdir(storeDir, { recursive: true });
-    await writeFile(scheduleRecord(storeDir), `${JSON.stringify({ schedule: 'off' })}\n`, { mode: 0o600 });
-};
-/** What a plain `hook install` says when the operator turned the nightly task off: it is left alone. */
-export const SCHEDULE_LEFT_OFF = `Scheduled task ${TASK_NAME}: left off, as you chose with --schedule off. Turn it back on with: oars sessions hook install --schedule nightly`;
+/** What `hook install` says to someone who asks for the task that earlier versions registered: sends ride the hook and the commands now. */
+export const SCHEDULE_REFUSED = 'oars no longer registers a scheduled task: sends now ride the session-end hook and any oars command (at most about hourly). Run: oars sessions hook install';
 /**
- * What a plain `hook install` does about the nightly task on Windows: register it unless it is already there. Registration is
- * best effort: the hooks are installed by then, so a machine that refuses the task (policy, no Task Scheduler) is told how to retry
- * and is not failed. `install --schedule off` removes the task and records the opt-out (`recordSchedule`), which the caller checks
- * (`scheduleOptedOut`) before calling this; `--schedule nightly` clears it.
+ * Removes the nightly task an earlier version registered, and says so in one line; nothing when it is not there. Only Windows ever had one, so any other platform makes no call. Install and uninstall both
+ * call this, so a machine that upgrades loses the task the first time either runs. A task that is there but refuses to go (policy) is reported, never failed: the hooks are the work of the command.
  */
-export const ensureSchedule = async (runtime) => {
+export const removeSchedule = async (runtime) => {
+    if (runtime.platform !== 'win32')
+        return undefined;
     const queried = await runtime.schtasks(['/Query', '/TN', TASK_NAME]);
-    if (queried.code === 0)
-        return `Scheduled task ${TASK_NAME}: already registered.`;
-    const created = await runtime.schtasks(scheduleArgs(runtime, SCHEDULE_HOUR));
-    if (created.code !== 0)
-        return `Could not register the scheduled task ${TASK_NAME} (${created.output.trim()}); the hooks are installed. Retry with: oars sessions hook install --schedule nightly`;
-    return registered();
+    if (queried.code !== 0)
+        return undefined;
+    const deleted = await runtime.schtasks(['/Delete', '/TN', TASK_NAME, '/F']);
+    return deleted.code === 0
+        ? `Removed the scheduled task ${TASK_NAME} that an earlier version registered; sends now ride the session-end hook and any oars command.`
+        : `Could not remove the scheduled task ${TASK_NAME} (${deleted.output.trim()}); remove it yourself with: schtasks /Delete /TN ${TASK_NAME} /F`;
 };
+/** The status line for a task left over from an earlier version; nothing when there is none. */
 export const scheduleStatus = async (runtime) => {
+    if (runtime.platform !== 'win32')
+        return undefined;
     const queried = await runtime.schtasks(['/Query', '/TN', TASK_NAME]);
-    return queried.code === 0 ? `Scheduled task ${TASK_NAME}: registered.` : `Scheduled task ${TASK_NAME}: not registered.`;
+    return queried.code === 0 ? `Scheduled task ${TASK_NAME}: registered by an earlier version; oars sessions hook install or uninstall removes it.` : undefined;
 };

package/dist/sessions/load-status.d.ts

@@ -0,0 +1,41 @@
+import { type CandidateSnapshot, type HookSource, type InstructionPosition, type WorkingKind } from './candidates.js';
+import type { LoadedInstructions, SessionObservation } from './schema.js';
+export declare const LOAD_STATUS_VERSION = 3;
+export declare const LOAD_STATUS_FILE = "load-status.jsonl";
+/** `loaded` the log shows it. `miss` a file existed, the rule loads it, the log does not show it. `excluded` a file existed where the rule skips by design. `absent` no file existed there. `unknown` this cannot be decided. */
+export type LoadLabel = 'loaded' | 'miss' | 'excluded' | 'absent' | 'unknown';
+export interface LoadStatus {
+    v: number;
+    session: string;
+    harness: string;
+    instructions: {
+        [position in InstructionPosition]: LoadLabel;
+    };
+    /** `CLAUDE.local.md`, `.claude/CLAUDE.md`, and the unconditional `.claude/rules/` files, in the working folder. */
+    files: {
+        [kind in WorkingKind]: LoadLabel;
+    };
+    skills: {
+        project: LoadLabel;
+        user: LoadLabel;
+    };
+    hooks: {
+        [source in HookSource]: LoadLabel;
+    };
+}
+/**
+ * The loaded set of a transcript's `instructions` record, as levels above the working folder: the path itself is read here and goes no further. `CLAUDE.md` files are placed by level;
+ * `CLAUDE.local.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md` are counted when they sit in the working folder, the only place they were measured.
+ */
+export declare const loadedInstructionsOf: (files: readonly {
+    path: string;
+    type: string;
+}[], cwd: string) => LoadedInstructions;
+export declare const loadStatusOf: ({ session, harness, snapshot, loaded }: {
+    session: string;
+    harness: string;
+    snapshot: CandidateSnapshot | undefined;
+    loaded: LoadedInstructions | undefined;
+}) => LoadStatus;
+/** One row per session, as the text of `load-status.jsonl`. Snapshots that cannot be read leave every session `unknown`: a store problem here must not stop a deposit. */
+export declare const loadStatusLines: (storeDir: string, sessions: readonly Pick<SessionObservation, "session" | "harness" | "loadedInstructions">[]) => Promise<string>;

package/dist/sessions/load-status.js

@@ -0,0 +1,156 @@
+// Did the harness load what existed: the session-start snapshot (`candidates.ts`) joined with the loaded set a transcript shows. A pure derivation, recomputed from those two
+// records, so a change to a rule below bumps LOAD_STATUS_VERSION and needs no new capture. `load-status.jsonl` is rewritten from them and is safe to delete.
+//
+// The rule is what a fixture measured for each harness, not what a harness documents: a live session per case on a temp tree, reading only that session's own log. Each position
+// is one of `load` (the harness read a file there), `skip` (it did not, by design), or `unmeasured` (the case was not measured). What was not measured stays `unknown`.
+//
+// What a log can show decides which kind gets a loaded or missed label. A transcript names each instruction file it loaded, so those kinds do. It lists each skill by name (only when the session offers the Skill tool) and each Stop hook by command, with no source for either; a `SessionStart` hook that prints nothing leaves no line. The snapshot holds
+// kinds and counts only, so it has no name or command to join against, and a skill or hook that exists stays `unknown`. A hook in a folder above the working folder is the one by-design skip measured for them: those settings files do not run.
+import { positionOfLevel, readCandidates } from './candidates.js';
+export const LOAD_STATUS_VERSION = 3;
+export const LOAD_STATUS_FILE = 'load-status.jsonl';
+const RULES = new Map([
+    [
+        'claude-code',
+        {
+            // Climbs past the git root to the filesystem root. A linked worktree nested inside its main checkout skips exactly that span, and the climb resumes above it.
+            positions: { working: 'load', parent: 'load', above: 'load', mainCheckout: 'skip', user: 'load' },
+            files: true,
+            // Project settings come from the working folder alone: a settings file in a parent folder, the repo root, or a worktree's main checkout did not run.
+            hooksAbove: 'skip',
+        },
+    ],
+    [
+        'codex',
+        {
+            // Reads from the git root down to the working folder and stops there. The user-level file was not measured: this machine has none, and measuring needs a copied login.
+            positions: { working: 'load', parent: 'load', above: 'skip', mainCheckout: 'skip', user: 'unmeasured' },
+            files: false,
+            hooksAbove: 'unmeasured',
+        },
+    ],
+]);
+const INSTRUCTION_NAME = 'claude.md';
+const LOCAL_NAME = 'claude.local.md';
+const segmentsOf = (path) => {
+    const parts = path.split(/[\\/]+/).filter((part) => part !== '');
+    // Only a path with a drive letter is compared without case: elsewhere two spellings can be two folders.
+    return /^[A-Za-z]:$/.test(parts[0] ?? '') ? parts.map((part) => part.toLowerCase()) : parts;
+};
+const sameFolder = (folder, other) => folder.length === other.length && folder.every((part, index) => part === other[index]);
+/**
+ * The loaded set of a transcript's `instructions` record, as levels above the working folder: the path itself is read here and goes no further. `CLAUDE.md` files are placed by level;
+ * `CLAUDE.local.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md` are counted when they sit in the working folder, the only place they were measured.
+ */
+export const loadedInstructionsOf = (files, cwd) => {
+    const here = segmentsOf(cwd);
+    const levels = [];
+    let user = 0;
+    const kinds = { local: 0, dotClaude: 0, rules: 0 };
+    for (const { path, type } of files) {
+        const segments = segmentsOf(path);
+        const name = segments.at(-1)?.toLowerCase();
+        const folder = segments.slice(0, -1);
+        if (type === 'User') {
+            if (name === INSTRUCTION_NAME)
+                user += 1;
+        }
+        else if (type === 'Local') {
+            if (name === LOCAL_NAME && sameFolder(folder, here))
+                kinds.local += 1;
+        }
+        else if (type === 'Project') {
+            if (name?.endsWith('.md') === true && sameFolder(folder, [...here, '.claude', 'rules']))
+                kinds.rules += 1;
+            else if (name === INSTRUCTION_NAME && sameFolder(folder, [...here, '.claude']))
+                kinds.dotClaude += 1;
+            else if (name === INSTRUCTION_NAME) {
+                if (folder.length <= here.length && folder.every((part, index) => part === here[index]))
+                    levels.push(here.length - folder.length);
+            }
+        }
+    }
+    return { user, levels, ...kinds };
+};
+/** How many files the log shows loaded at a position: the user count, or the project files whose folder level falls in the position. */
+const seenAt = (position, snapshot, loaded) => {
+    if (position === 'user')
+        return loaded.user;
+    return loaded.levels.filter((level) => positionOfLevel(level, snapshot) === position).length;
+};
+const instructionLabel = (position, snapshot, loaded, rules) => {
+    const present = snapshot.instructions[position];
+    if (loaded === undefined)
+        return present === 0 ? 'absent' : 'unknown';
+    const seen = seenAt(position, snapshot, loaded);
+    // What the log shows wins over what the snapshot counted and over the rule: the file was loaded.
+    if (seen > 0)
+        return 'loaded';
+    if (present === 0)
+        return 'absent';
+    const rule = rules[position];
+    if (rule === 'unmeasured')
+        return 'unknown';
+    // A file the harness does not read by design is not a candidate, so it is no miss; it is not absent either, since it exists.
+    return rule === 'load' ? 'miss' : 'excluded';
+};
+/** A working-folder kind: the log shows how many of its files loaded, once a capture of version 30 or later recorded it. */
+const kindLabel = (present, seen, measured) => {
+    if (seen === undefined)
+        return present === 0 ? 'absent' : 'unknown';
+    if (seen > 0)
+        return 'loaded';
+    if (present === 0)
+        return 'absent';
+    return measured ? 'miss' : 'unknown';
+};
+/** The log names skills without a source and the snapshot holds only counts, so a count above zero cannot be called either way. */
+const countLabel = (count) => (count === 0 ? 'absent' : 'unknown');
+const total = (counts) => Object.values(counts).reduce((sum, count) => sum + count, 0);
+/** A hook is `absent` at zero. Above zero the log gives no source and the snapshot holds only counts, so it is `unknown`, except where the rule skips its settings file by design. */
+const hookLabel = (counts, skippedByDesign) => {
+    if (total(counts) === 0)
+        return 'absent';
+    return skippedByDesign ? 'excluded' : 'unknown';
+};
+const allPositions = (label) => ({
+    working: label('working'),
+    parent: label('parent'),
+    above: label('above'),
+    mainCheckout: label('mainCheckout'),
+    user: label('user'),
+});
+export const loadStatusOf = ({ session, harness, snapshot, loaded }) => {
+    const rule = RULES.get(harness);
+    // No snapshot means nothing is known of what existed: never `absent`.
+    if (snapshot === undefined) {
+        return {
+            v: LOAD_STATUS_VERSION,
+            session,
+            harness,
+            instructions: allPositions(() => 'unknown'),
+            files: { local: 'unknown', dotClaude: 'unknown', rules: 'unknown' },
+            skills: { project: 'unknown', user: 'unknown' },
+            hooks: { user: 'unknown', working: 'unknown', ancestors: 'unknown' },
+        };
+    }
+    const fileLabel = (kind) => (rule === undefined ? 'unknown' : kindLabel(snapshot.workingKinds[kind], loaded?.[kind], rule.files));
+    return {
+        v: LOAD_STATUS_VERSION,
+        session,
+        harness,
+        instructions: allPositions((position) => (rule === undefined ? 'unknown' : instructionLabel(position, snapshot, loaded, rule.positions))),
+        files: { local: fileLabel('local'), dotClaude: fileLabel('dotClaude'), rules: fileLabel('rules') },
+        skills: { project: countLabel(snapshot.skills.project), user: countLabel(snapshot.skills.user) },
+        hooks: {
+            user: hookLabel(snapshot.hooks.user, false),
+            working: hookLabel(snapshot.hooks.working, false),
+            ancestors: hookLabel(snapshot.hooks.ancestors, rule?.hooksAbove === 'skip'),
+        },
+    };
+};
+/** One row per session, as the text of `load-status.jsonl`. Snapshots that cannot be read leave every session `unknown`: a store problem here must not stop a deposit. */
+export const loadStatusLines = async (storeDir, sessions) => {
+    const snapshots = await readCandidates(storeDir).catch(() => new Map());
+    return sessions.map((session) => `${JSON.stringify(loadStatusOf({ session: session.session, harness: session.harness ?? 'claude-code', snapshot: snapshots.get(session.session), loaded: session.loadedInstructions }))}\n`).join('');
+};

package/dist/sessions/machine-child-deps.d.ts

@@ -0,0 +1,5 @@
+import { type SettleTimes } from './machine-child.js';
+import { type Sender } from './pool-command.js';
+import { type SessionsRuntime } from './store.js';
+/** Runs the child for one Stop's forwarded input (`text`, the one argument `machine-stop.ts` passes). `settle` replaces the settle wait's times, which a test shortens, and `via` the network a send goes over. */
+export declare const runMachineChild: (env: NodeJS.ProcessEnv, sessions: SessionsRuntime, version: string, now: () => number, text: string, settle?: SettleTimes, via?: Sender) => Promise<void>;

package/dist/sessions/machine-child-deps.js

@@ -0,0 +1,83 @@
+// The real parts of the machine child (`machine-child.ts`): the session store's capture, the pool's batch build, the file system and the clock. Loaded only by `hook-bin.js machine-child`, so a per-tool hook and the Stop
+// itself never pay for the store and pool modules. It never throws: a failure is one masked line in `pool-send.log`, and the next Stop builds the same batch.
+import { stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { exclusionPaths, loadTerms } from './exclusion.js';
+import { machineChild, parseChildInput } from './machine-child.js';
+import { holdBatch, runNetGit } from './machine-hold.js';
+import { DEPOSIT, machineKeyOf, poolDeposit, poolServer, vocabularyExpired } from './pool-command.js';
+import { machineOf, withInlineTerms } from './machine.js';
+import { machineSend } from './machine-send.js';
+import { recordNotice } from './machine-notice.js';
+import { repoAllowed } from './machine-repo.js';
+import { logFailure } from './pool-due.js';
+import { nightlyPoolDeps } from './pool-nightly-deps.js';
+import { currentStamp, heldBatchOf, outboxFolder } from './pool-outbox.js';
+import { depositSession } from './store.js';
+import { runGit } from './survival.js';
+/**
+ * Holds the session's batch on its branch in the session's own repository (`machine-hold.ts`). A machine holds only when its enrollment gave it a machine id (the branch's `<machine>`) and `OARS_SESSION_SALT` (the key of the terms digest); one
+ * enrolled without them builds into its outbox as before, and `runMachineChild` has told the person (before any gate, so a session a gate withdrew or a build that threw is told too). A session whose batch a gate withdrew has none in the outbox, so nothing is held for it.
+ */
+const holdSession = async (env, gated, sessions, now, machine, forwarded) => {
+    if (machine === undefined)
+        return;
+    const { machine: name, sessionSalt: salt } = machine;
+    if (name === undefined || salt === undefined)
+        return;
+    const id = machineKeyOf(machine, basename(forwarded.transcript, '.jsonl'));
+    const held = await heldBatchOf(outboxFolder(sessions.storeDir, poolServer(env, DEPOSIT)), id);
+    if (held === undefined)
+        return;
+    const terms = await loadTerms(exclusionPaths(sessions.projectsRoot, gated).terms);
+    await holdBatch({ git: runGit, net: runNetGit, log: (error) => logFailure(sessions.storeDir, now(), error) }, { cwd: forwarded.cwd, allowRepos: machine.allowRepos, machine: name, id, batch: held.bytes, stamp: currentStamp(), terms, salt });
+};
+/** Runs the child for one Stop's forwarded input (`text`, the one argument `machine-stop.ts` passes). `settle` replaces the settle wait's times, which a test shortens, and `via` the network a send goes over. */
+export const runMachineChild = async (env, sessions, version, now, text, settle, via) => {
+    const input = parseChildInput(text);
+    if (input === undefined)
+        return;
+    try {
+        // The terms the enrollment put in one variable are written to an owner-only file first, so every gate below reads the term file the way it always does.
+        const gated = await withInlineTerms(env, sessions.storeDir);
+        const repoSalt = env.OARS_REPO_SALT?.trim();
+        const keyed = repoSalt === undefined || repoSalt === '' ? sessions : { ...sessions, repoSalt };
+        const deps = nightlyPoolDeps(gated, keyed, version, now);
+        // A client past its vocabulary's age builds no batch and its sessions wait. The child has no terminal, so the next Stop tells the person, from the notice file; nothing is captured or built until the client is upgraded.
+        if (vocabularyExpired(deps) !== undefined) {
+            await recordNotice(sessions.storeDir, 'vocabulary_expired', now());
+            return;
+        }
+        const machine = machineOf(env);
+        // A machine that cannot hold loses its session's data unseen, so the person is told at every Stop, before the work that can fail or withdraw: the next Stop prints it once.
+        if (machine !== undefined && (machine.machine === undefined || machine.sessionSalt === undefined))
+            await recordNotice(sessions.storeDir, 'hold_unconfigured', now());
+        const allowRepos = machine?.allowRepos ?? [];
+        await machineChild({
+            outbox: outboxFolder(sessions.storeDir, poolServer(env, DEPOSIT)),
+            now,
+            ...(settle === undefined ? {} : { settle }),
+            // The operator's repository list: the child builds a session only for a repository `origin` names on it.
+            allowed: (forwarded) => repoAllowed(allowRepos, forwarded.cwd, runGit),
+            sleep: async (ms) => {
+                await sleep(ms);
+            },
+            size: (path) => stat(path).then((found) => found.size, () => undefined),
+            capture: async (forwarded) => {
+                await depositSession(keyed, forwarded.transcript, now);
+            },
+            // The store names a session by its transcript's file name, which is what the Stop's session is on every harness this build runs under.
+            build: async (forwarded) => {
+                await poolDeposit(deps, { session: basename(forwarded.transcript, '.jsonl') });
+            },
+            hold: (forwarded) => holdSession(env, gated, sessions, now, machine, forwarded),
+            send: async () => {
+                await machineSend(deps, via);
+            },
+        }, input);
+    }
+    catch (error) {
+        await logFailure(sessions.storeDir, now(), error);
+    }
+};

package/dist/sessions/machine-child.d.ts

@@ -0,0 +1,43 @@
+import { type LockTimes } from './pool-send-lock.js';
+/** What a Stop forwards: the session, its transcript, and the folder it ran in (the repository the allow list is checked against). */
+export interface ChildInput {
+    session: string;
+    transcript: string;
+    cwd: string | undefined;
+}
+export interface SettleTimes {
+    /** The transcript must be this long unchanged. */
+    quietMs: number;
+    /** The wait is never longer than this: a transcript still growing is captured as it is. */
+    maxMs: number;
+    pollMs: number;
+}
+export declare const SETTLE: SettleTimes;
+export interface MachineChildDeps {
+    outbox: string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    /** The transcript's size, or `undefined` when it cannot be read. */
+    size: (path: string) => Promise<number | undefined>;
+    /** Whether the session's repository is on the operator's allow list (`machine-repo.ts`); a session that is not is neither captured nor built. */
+    allowed: (input: ChildInput) => Promise<boolean>;
+    /** Captures the transcript (and its subagents) into the session store. */
+    capture: (input: ChildInput) => Promise<void>;
+    /** Builds the session's batch into the outbox, with the gates. */
+    build: (input: ChildInput) => Promise<void>;
+    /** Commits the batch just built to the session's holding branch and pushes it (`machine-hold.ts`); a refused push is the step's own log row, not a throw. */
+    hold: (input: ChildInput) => Promise<void>;
+    /** Activates the machine's key and sends what its outbox holds once the covenant is accepted (`machine-send.ts`); it never throws, and a refusal is its own log row. Under the same lock as the build. */
+    send?: () => Promise<void>;
+    settle?: SettleTimes;
+    lock?: Partial<LockTimes>;
+}
+/** The input a Stop forwarded, or `undefined` when it names no session or transcript. */
+export declare const parseChildInput: (text: string) => ChildInput | undefined;
+/** Waits until the transcript has been the same size for `quietMs`, at most `maxMs` in all. */
+export declare const settle: (path: string, deps: Pick<MachineChildDeps, "now" | "sleep" | "size">, times?: SettleTimes) => Promise<"quiet" | "timeout">;
+/**
+ * `built` when this child ran the session (and anything marked while it did), `marked` when another child held the lock and the mark is left for it. Two windows are closed on purpose: a Stop that marks just after the holder's last look
+ * finds the lock free on its second try, and a holder that lets go while a mark is being written looks once more after it has released.
+ */
+export declare const machineChild: (deps: MachineChildDeps, input: ChildInput) => Promise<"built" | "marked">;