@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/commands/resume.js

@@ -0,0 +1,88 @@
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { EPHEMERAL_DIRS, classifyLayoutEntry, missingDurableEntries, } from "../fleet.js";
+/**
+ * The plan, or the one reason it cannot be made. Deciding every entry BEFORE
+ * creating any of them is what makes criterion 2's "creates nothing" true of
+ * the refusal arms: a refusal discovered halfway through a creating loop has
+ * already changed the tree.
+ */
+function planRebuild(root) {
+    const steps = [];
+    for (const name of EPHEMERAL_DIRS) {
+        const entry = classifyLayoutEntry(join(root, name));
+        if (entry.kind === "directory") {
+            steps.push({ name, rebuild: false });
+            continue;
+        }
+        if (entry.kind === "absent") {
+            steps.push({ name, rebuild: true });
+            continue;
+        }
+        return {
+            refusal: `tiphys resume: ${root} cannot be rehydrated: ${entry.reason}, ` +
+                `and resume never removes anything to make room`,
+        };
+    }
+    return { steps };
+}
+export function cmdResume(args) {
+    const [dir, ...extra] = args;
+    if (extra.length > 0) {
+        process.stderr.write("usage: tiphys resume [dir]\n");
+        return EX_USAGE;
+    }
+    const root = resolve(dir ?? ".");
+    const rootEntry = classifyLayoutEntry(root);
+    if (rootEntry.kind !== "directory") {
+        process.stderr.write(`tiphys resume: ${root} is not a directory, so there is no fleet home here to rebuild\n`);
+        return 1;
+    }
+    /* THE FIRST PRECONDITION: a fleet home is a git repository, and a clone of
+       one is what this command exists to repair. A directory with no `.git` is
+       not a fleet clone whatever else it holds, and creating three directories
+       inside it would be a success report about a fleet that does not exist. */
+    const gitEntry = classifyLayoutEntry(join(root, ".git"));
+    if (gitEntry.kind === "absent") {
+        process.stderr.write(`tiphys resume: ${root} is not a git repository, .git is absent, ` +
+            `so it is not a cloned fleet home; run tiphys init <dir> to create one\n`);
+        return 1;
+    }
+    if (gitEntry.kind === "unexaminable") {
+        process.stderr.write(`tiphys resume: ${gitEntry.reason}\n`);
+        return 1;
+    }
+    /* THE SECOND PRECONDITION, and it is a different failure from the first.
+       A git repository that is not a fleet home (any other clone, including the
+       kernel's own) passes the `.git` test. Rebuilding the ephemeral three
+       inside it would litter a stranger's repository and report success. The
+       durable entries are what a clone of a fleet home carries, so their absence
+       means either "not a fleet home" or "a fleet home that has lost durable
+       content", and resume fabricates NEITHER: durable content comes back from
+       the remote, never from this command. */
+    const missingDurable = missingDurableEntries(root);
+    if (missingDurable.length > 0) {
+        process.stderr.write(`tiphys resume: ${root} is a git repository but not a fleet home, ` +
+            `missing ${missingDurable.join(", ")}; durable content is restored by ` +
+            `fetching from the remote, never by resume\n`);
+        return 1;
+    }
+    const planned = planRebuild(root);
+    if ("refusal" in planned) {
+        process.stderr.write(`${planned.refusal}\n`);
+        return 1;
+    }
+    /* PER ENTRY, never all-or-nothing. An interrupted resume leaves a
+       half-rebuilt layout, and that half is the common case rather than an edge:
+       rebuilding the set because one member is missing is how a live worktree
+       that survived the reclaim gets reported as rebuilt when it was not. */
+    for (const step of planned.steps) {
+        if (!step.rebuild) {
+            continue;
+        }
+        mkdirSync(join(root, step.name));
+        process.stdout.write(`REBUILT ${step.name}/\n`);
+    }
+    return 0;
+}

package/dist/src/commands/spawn.js

@@ -6,7 +6,9 @@ import { singleLine } from "../task.js";
 /**
  * tiphys spawn --task <id> --project <path> --brief <file> --shape
  * ship|scout --exec <cmd> [--deadline <seconds>] [--offline]
- * (kernel plan v1, M1-P4 step 4). Runs in a fleet home (cwd).
+ * [--role <name>] [--tier <name>] [--phase <id>] [--adapter <specifier>]
+ * (kernel plan v1, M1-P4 step 4; --role, --tier and --phase added by
+ * M4-P3 and --adapter by M4-P4). Runs in a fleet home (cwd).
  *
  * --exec is REQUIRED in M1: spawn without it exits 64 with usage,
  * because the multiplexer-window adapter that would make an exec-less
@@ -22,7 +24,8 @@ import { singleLine } from "../task.js";
  * worktree a task's meta describes.
  */
 const USAGE = "usage: tiphys spawn --task <id> --project <path> --brief <file> " +
-    "--shape ship|scout --exec <cmd> [--deadline <seconds>] [--offline]";
+    "--shape ship|scout --exec <cmd> [--deadline <seconds>] [--offline] " +
+    "[--role <name>] [--tier <name>] [--phase <id>] [--adapter <specifier>]";
 function usageError(message) {
     if (message !== undefined) {
         process.stderr.write(`tiphys spawn: ${message}\n`);
@@ -39,6 +42,10 @@ function parseFlags(args) {
         exec: undefined,
         deadlineSeconds: undefined,
         offline: false,
+        role: undefined,
+        tier: undefined,
+        phase: undefined,
+        adapter: undefined,
     };
     for (let i = 0; i < args.length; i += 1) {
         const flag = args[i];
@@ -82,6 +89,34 @@ function parseFlags(args) {
             parsed.deadlineSeconds = seconds;
             i += 1;
         }
+        else if (flag === "--role" && value !== undefined) {
+            parsed.role = value;
+            i += 1;
+        }
+        else if (flag === "--tier" && value !== undefined) {
+            // VERBATIM, and deliberately unvalidated: this is the DECLARED TIER,
+            // whatever role-model-config.yaml declares, and the tier-to-model
+            // mapping lives in the plugin. A kernel that checked this value
+            // against a list would be holding the vocabulary the plugin owns.
+            parsed.tier = value;
+            i += 1;
+        }
+        else if (flag === "--phase" && value !== undefined) {
+            // CARRIED, never derived from the branch name (M4-D-22 is open).
+            parsed.phase = value;
+            i += 1;
+        }
+        else if (flag === "--adapter" && value !== undefined) {
+            // VERBATIM, and it is a MODULE SPECIFIER rather than a path: the
+            // kernel resolves it with Node module resolution rooted at the fleet
+            // home (src/adapters/load.ts), which is the one root that is
+            // owner-controlled. Nothing is checked here, because a check here
+            // would run against this process's own resolution root, which is the
+            // kernel checkout, and that is precisely the root this phase exists to
+            // keep out of the answer.
+            parsed.adapter = value;
+            i += 1;
+        }
         else if (flag === "--offline") {
             parsed.offline = true;
         }
@@ -128,6 +163,20 @@ export async function cmdSpawn(args) {
         exec: flags.exec,
         deadlineSeconds: flags.deadlineSeconds,
         offline: flags.offline,
+        /*
+         * PROJECT, ALWAYS, AND THE CLI HAS NO FLAG TO SAY OTHERWISE (M4-P8
+         * step 2). `tiphys spawn` launches a payload into a project worktree,
+         * and the declared credential escape hatch is not reachable from this
+         * command at all: `allowPrCredentials` is a library-seam field with no
+         * flag behind it, which is exactly why the orchestrator class is not
+         * offered here. An operator who could type --payload-class orchestrator
+         * would be able to ask for the pairing spawnTask exists to refuse.
+         */
+        payloadClass: "project",
+        role: flags.role,
+        declaredTier: flags.tier,
+        phaseId: flags.phase,
+        adapterSpecifier: flags.adapter,
     });
     if (!result.ok) {
         // One reason line, structurally (CR-303): a reason may carry a

package/dist/src/commands/status.d.ts

@@ -7,10 +7,12 @@
  *
  * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
  * the shipped `status-line` schema before writing anything, appends one line
- * to `state/status/stream.jsonl`, then rewrites `state/status/current.json`
- * atomically. `show` reads `current.json` ONLY and never opens the stream
- * (constraint C-1: never read current state from the tail of an append-only
- * log).
+ * to `state/status/stream.jsonl`, then rewrites the DURABLE
+ * `status/current.json` atomically. `show` reads `current.json` ONLY and
+ * never opens the stream (constraint C-1: never read current state from the
+ * tail of an append-only log). The two documents sit on opposite sides of the
+ * fleet `.gitignore` since M4-D-13, which is why the paths differ in prefix;
+ * src/status.ts carries the reasoning.
  *
  * The state vocabulary is closed and is enforced, not requested: `--state
  * progress` is refused naming the permitted values, because R-084's

package/dist/src/commands/status.js

@@ -7,10 +7,12 @@
  *
  * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
  * the shipped `status-line` schema before writing anything, appends one line
- * to `state/status/stream.jsonl`, then rewrites `state/status/current.json`
- * atomically. `show` reads `current.json` ONLY and never opens the stream
- * (constraint C-1: never read current state from the tail of an append-only
- * log).
+ * to `state/status/stream.jsonl`, then rewrites the DURABLE
+ * `status/current.json` atomically. `show` reads `current.json` ONLY and
+ * never opens the stream (constraint C-1: never read current state from the
+ * tail of an append-only log). The two documents sit on opposite sides of the
+ * fleet `.gitignore` since M4-D-13, which is why the paths differ in prefix;
+ * src/status.ts carries the reasoning.
  *
  * The state vocabulary is closed and is enforced, not requested: `--state
  * progress` is refused naming the permitted values, because R-084's

package/dist/src/commands/sync.d.ts

@@ -0,0 +1,47 @@
+/** The remote a fleet home pushes to unless told otherwise. */
+export declare const DEFAULT_REMOTE = "origin";
+/**
+ * The commit subject, and it carries NO PATHS ON PURPOSE (criterion 6,
+ * CLAUDE.md binding convention 7: commit messages carry no AI model or tool
+ * names). A message composed from the paths it commits inherits whatever
+ * those paths are named, and a fleet's decision records and task directories
+ * are named after the things they decide, which routinely includes the
+ * harness or the model a decision is about. A count cannot carry a name.
+ */
+export declare function syncCommitMessage(count: number): string;
+/** One path git reports as changed, with its two status columns. */
+export interface ChangedPath {
+    path: string;
+    /** The index column (X). A space means unstaged; `?` means untracked. */
+    index: string;
+    /** The worktree column (Y). */
+    worktree: string;
+}
+/**
+ * Parse `git status --porcelain=v1 -z --untracked-files=all`.
+ *
+ * The NUL form is the only safe one: a path holding a space, a quote or a
+ * newline is printed raw here and is C-quoted in the newline form, so the
+ * newline form would need an unquoting pass that is its own defect surface.
+ * A rename or copy record carries TWO paths, the new one first and the
+ * original second, and both are returned: a rename out of the durable half
+ * into the ephemeral half must be visible as a change to both names.
+ */
+export declare function parsePorcelainStatus(payload: string): ChangedPath[];
+/** The `.gitignore` rule that makes one path ephemeral. */
+export interface IgnoreRule {
+    source: string;
+    line: string;
+    pattern: string;
+}
+/**
+ * Parse `git check-ignore --no-index -v -z --stdin`, whose output is a flat
+ * NUL-separated stream of four fields per MATCHING path: source, line
+ * number, pattern, pathname. Paths that match no rule are absent from the
+ * output entirely, which is what makes the result a set of the ephemeral
+ * ones rather than a verdict per input.
+ */
+export declare function parseCheckIgnore(payload: string): Map<string, IgnoreRule>;
+/** How an ignore rule is named in every line this command prints. */
+export declare function renderRule(rule: IgnoreRule): string;
+export declare function cmdSync(argv: string[]): number;

package/dist/src/commands/sync.js

@@ -0,0 +1,341 @@
+import { spawnSync } from "node:child_process";
+import { EX_USAGE } from "../cli.js";
+import { FLEET_SCRATCH_SUFFIXES, isFleetScratchPath, loadFleet } from "../fleet.js";
+import { MACHINE_IDENTITY_EMAIL, MACHINE_IDENTITY_NAME } from "./init.js";
+/**
+ * `tiphys sync`: commit the durable half of a fleet home and push it
+ * (kernel plan M4, M4-P18).
+ *
+ * WHAT THIS IS THE EXECUTABLE HALF OF. AGENTS.md's
+ * `fleet-state-commit-discipline` clause says durable state is committed and
+ * pushed at the moment it changes, and that the PUSH is the half that gets
+ * dropped. Until this phase the whole clause was discharged by an agent
+ * remembering to run git, which is the shape this repository has recorded
+ * three times: a rule that depends on remembering does not survive a busy
+ * session, and the answer is a mechanism.
+ *
+ * THE DURABLE SET IS DERIVED, NEVER LISTED HERE (criterion 2). A second list
+ * of ephemeral prefixes inside this file would be a second thing to keep in
+ * step with the fleet's own `.gitignore`, and the first divergence would be
+ * silent: a prefix added to the ignore set would keep being committed by a
+ * command that had never heard of it. So the question "is this path
+ * ephemeral" is answered by GIT, against the fleet `.gitignore` that
+ * `tiphys init` wrote, and this module holds no prefix list at all.
+ *
+ * `--no-index` IS THE LOAD-BEARING FLAG AND THE REASON IS THE HAZARD ITSELF.
+ * `git check-ignore` without it answers "would git ignore this path", and a
+ * TRACKED file is never ignored whatever `.gitignore` says, so it answers 1
+ * for exactly the file this command must exclude. The dangerous state is a
+ * lease or a scratch file that got tracked once (by a `git add -f`, or by
+ * being committed before the prefix was ignored): from then on every `git
+ * add -A` re-commits it, and a fleet's lease travels through the remote to
+ * environments that must rebuild it rather than restore it. With
+ * `--no-index` the answer is about the RULES, which is the question being
+ * asked. Measured contract in witness/captures/m4-p18-git-contracts.txt.
+ *
+ * WHY A STAGED EPHEMERAL PATH IS A REFUSAL AND NOT A SKIP (criterion 4).
+ * This command stages the durable paths it enumerated and then commits, and
+ * `git commit` commits the INDEX, not the pathspec it was handed. An
+ * operator who ran `git add -A` first has already put the lease in the
+ * index, so committing at all would commit it. Unstaging on the operator's
+ * behalf is a destructive act on work this command did not create, so the
+ * refusal names the path and the rule that makes it ephemeral, and commits
+ * nothing.
+ *
+ * SUBSTRATE-NEUTRAL (DR-0007) and C-2 clean: pure git and filesystem, no
+ * process probing, no pid, no signal.
+ */
+const USAGE = "usage: tiphys sync [--remote <name>]";
+/** The remote a fleet home pushes to unless told otherwise. */
+export const DEFAULT_REMOTE = "origin";
+/**
+ * The commit subject, and it carries NO PATHS ON PURPOSE (criterion 6,
+ * CLAUDE.md binding convention 7: commit messages carry no AI model or tool
+ * names). A message composed from the paths it commits inherits whatever
+ * those paths are named, and a fleet's decision records and task directories
+ * are named after the things they decide, which routinely includes the
+ * harness or the model a decision is about. A count cannot carry a name.
+ */
+export function syncCommitMessage(count) {
+    return `tiphys sync: ${String(count)} durable path(s)`;
+}
+function runGit(root, args, options = {}) {
+    const run = spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        input: options.input,
+        env: options.extraEnv === undefined
+            ? process.env
+            : { ...process.env, ...options.extraEnv },
+    });
+    return {
+        status: run.status,
+        stdout: run.stdout ?? "",
+        stderr: run.stderr ?? "",
+    };
+}
+/**
+ * Parse `git status --porcelain=v1 -z --untracked-files=all`.
+ *
+ * The NUL form is the only safe one: a path holding a space, a quote or a
+ * newline is printed raw here and is C-quoted in the newline form, so the
+ * newline form would need an unquoting pass that is its own defect surface.
+ * A rename or copy record carries TWO paths, the new one first and the
+ * original second, and both are returned: a rename out of the durable half
+ * into the ephemeral half must be visible as a change to both names.
+ */
+export function parsePorcelainStatus(payload) {
+    const fields = payload.split("\0");
+    const found = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const record = fields[index];
+        if (record === "") {
+            continue;
+        }
+        const x = record.slice(0, 1);
+        const y = record.slice(1, 2);
+        const path = record.slice(3);
+        found.push({ path, index: x, worktree: y });
+        if (x === "R" || x === "C" || y === "R" || y === "C") {
+            const original = fields[index + 1];
+            index += 1;
+            if (original !== undefined && original !== "") {
+                found.push({ path: original, index: x, worktree: y });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Parse `git check-ignore --no-index -v -z --stdin`, whose output is a flat
+ * NUL-separated stream of four fields per MATCHING path: source, line
+ * number, pattern, pathname. Paths that match no rule are absent from the
+ * output entirely, which is what makes the result a set of the ephemeral
+ * ones rather than a verdict per input.
+ */
+export function parseCheckIgnore(payload) {
+    const fields = payload.split("\0");
+    const found = new Map();
+    for (let index = 0; index + 3 < fields.length; index += 4) {
+        const source = fields[index];
+        const line = fields[index + 1];
+        const pattern = fields[index + 2];
+        const path = fields[index + 3];
+        if (path === "") {
+            continue;
+        }
+        found.set(path, { source, line, pattern });
+    }
+    return found;
+}
+/** How an ignore rule is named in every line this command prints. */
+export function renderRule(rule) {
+    return `${rule.source}:${rule.line} ${rule.pattern}`;
+}
+/**
+ * Ask git which of these paths the fleet `.gitignore` covers.
+ *
+ * THE THREE EXIT CODES ARE NOT TWO. 0 means at least one path matched, 1
+ * means none did, and 128 means git could not answer at all. Folding 128
+ * into "nothing is ephemeral" is how a command reports a clean sync while
+ * committing a lease, so it is a refusal here and the exit code is named.
+ */
+function classify(root, paths) {
+    if (paths.length === 0) {
+        return { ok: true, ephemeral: new Map() };
+    }
+    const run = runGit(root, ["check-ignore", "--no-index", "-v", "-z", "--stdin"], {
+        input: `${paths.join("\0")}\0`,
+    });
+    if (run.status === 0) {
+        return { ok: true, ephemeral: parseCheckIgnore(run.stdout) };
+    }
+    if (run.status === 1) {
+        return { ok: true, ephemeral: new Map() };
+    }
+    return {
+        ok: false,
+        reason: `git check-ignore exited ${String(run.status)} and could not say which paths are ephemeral, ` +
+            `so nothing was committed: ${run.stderr.split("\n")[0] ?? ""}`,
+    };
+}
+function parseArgs(argv) {
+    let remote = DEFAULT_REMOTE;
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        if (flag !== "--remote") {
+            return { usageError: `unknown option ${flag}` };
+        }
+        const value = argv[index + 1];
+        if (value === undefined) {
+            return { usageError: "--remote requires a value" };
+        }
+        remote = value;
+        index += 1;
+    }
+    return { remote };
+}
+export function cmdSync(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.remote === undefined) {
+        process.stderr.write(`tiphys sync: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const remote = parsed.remote;
+    const fleet = loadFleet(process.cwd());
+    /* THE REMOTE IS ESTABLISHED BEFORE ANYTHING IS COMMITTED. The discipline
+       is commit AND push; a sync that commits and then discovers there is
+       nowhere to push has done the half that gets dropped and reported the
+       half that does not. */
+    const remotes = runGit(fleet.root, ["remote"]);
+    if (remotes.status !== 0) {
+        process.stderr.write(`tiphys sync: git remote failed in ${fleet.root}: ${remotes.stderr.split("\n")[0] ?? ""}\n`);
+        return 1;
+    }
+    const known = remotes.stdout.split("\n").map((line) => line.trim());
+    if (!known.includes(remote)) {
+        process.stderr.write(`tiphys sync: ${fleet.root} has no remote named ${remote}, so durable state cannot be pushed; ` +
+            `add one with git remote add ${remote} <url>, nothing was committed\n`);
+        return 1;
+    }
+    const status = runGit(fleet.root, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+    ]);
+    if (status.status !== 0) {
+        process.stderr.write(`tiphys sync: git status failed in ${fleet.root}: ${status.stderr.split("\n")[0] ?? ""}\n`);
+        return 1;
+    }
+    const changed = parsePorcelainStatus(status.stdout);
+    const classified = classify(fleet.root, [...new Set(changed.map((entry) => entry.path))]);
+    if (!classified.ok) {
+        process.stderr.write(`tiphys sync: ${classified.reason}\n`);
+        return 1;
+    }
+    const ephemeral = classified.ephemeral;
+    /* THE SCRATCH REFUSAL RUNS BEFORE THE STAGED-EPHEMERAL ONE, and the order
+       is stated because it is a choice. A fleet carrying both a stray scratch
+       file and a staged ephemeral path reports the scratch file and stops; both
+       arms refuse and commit nothing, so no path is committed either way, and
+       the operator sees one refusal at a time rather than two. It also keeps the
+       staged-ephemeral block the last `return 1` before `const durable`, which
+       is where witness/sync-staged-lease-refused.json aims its second member. */
+    /* THE DENYLIST IS THREE DIRECTORY PREFIXES AND THE QUESTION IT ANSWERS IS
+       NARROWER THAN THE ONE THIS COMMAND ASKS.
+  
+       `git check-ignore --no-index` answers "is this path covered by a rule
+       someone wrote down". This command reads that as "is this path meant to
+       be committed". Those are the same question only for paths someone
+       thought to declare, and the fleet ignore set (src/fleet.ts:29) declares
+       three directory prefixes and nothing else. Anything the kernel writes
+       outside them is DURABLE BY DEFAULT.
+  
+       Two paths the kernel itself creates land there, and neither is fleet
+       content: the atomic-rename scratch file src/status.ts:142 writes beside
+       its TRACKED target, and the one src/cutover.ts:278 writes at the fleet
+       ROOT under a random name. Both are write-then-rename scratch, both are
+       left behind by the failure this project's own tuition calls ordinary
+       rather than exceptional (a process killed mid-write), and once either is
+       committed it is tracked forever by ordinary git semantics.
+  
+       A REFUSAL AND NOT A SILENT EXCLUSION, for the reason criterion 4 already
+       gives about a staged ephemeral path: this command must not quietly drop
+       a path an operator can see in `git status`. The cost is stated rather
+       than discovered: a `tiphys sync` that races a live `tiphys status emit`
+       now fails with a named path instead of committing a temp file, and the
+       operator re-runs.
+  
+       THE FLEET IGNORE SET IS NOT WIDENED TO DO THIS, and this module still
+       holds no copy of it. That constant also drives `EPHEMERAL_DIRS`,
+       `DURABLE_DIRS` and the `.gitignore` `tiphys init` writes, so a glob
+       added there would become a directory name `tiphys resume` tried to
+       rebuild. Nothing stops being synced; this is a second, separately named
+       rule about SUFFIXES, declared once in src/fleet.ts and read from there,
+       exactly as the ignore question is asked of git rather than answered
+       here. */
+    const scratch = [...new Set(changed.map((entry) => entry.path))]
+        .filter((path) => !ephemeral.has(path))
+        .map((path) => ({ path, suffix: isFleetScratchPath(path) }))
+        .filter((candidate) => candidate.suffix !== undefined)
+        .sort((a, b) => a.path.localeCompare(b.path));
+    if (scratch.length > 0) {
+        for (const candidate of scratch) {
+            process.stderr.write(`tiphys sync: ${candidate.path} ends in ${candidate.suffix}, which is a ` +
+                `write-then-rename scratch suffix this kernel uses (${FLEET_SCRATCH_SUFFIXES.join(", ")}), ` +
+                `and no fleet .gitignore rule covers it, so committing it would track it forever; ` +
+                `remove it and re-run, nothing was committed\n`);
+        }
+        return 1;
+    }
+    /* CRITERION 4, and the order matters: every staged ephemeral path is
+       reported before anything is staged or committed, so the refusal is a
+       statement about the tree as the operator left it. */
+    const stagedEphemeral = changed.filter((entry) => ephemeral.has(entry.path) && entry.index !== " " && entry.index !== "?");
+    if (stagedEphemeral.length > 0) {
+        for (const entry of stagedEphemeral) {
+            const rule = ephemeral.get(entry.path);
+            process.stderr.write(`tiphys sync: ${entry.path} is staged and is ephemeral by ${renderRule(rule)}; ` +
+                `unstage it with git restore --staged -- ${entry.path} and re-run, nothing was committed\n`);
+        }
+        return 1;
+    }
+    const durable = [
+        ...new Set(changed
+            .map((entry) => entry.path)
+            .filter((path) => !ephemeral.has(path))),
+    ].sort();
+    const excluded = [
+        ...new Set(changed.map((entry) => entry.path).filter((path) => ephemeral.has(path))),
+    ].sort();
+    /* The excluded paths are PRINTED WITH THE RULE THAT EXCLUDED THEM. A
+       command that silently drops paths is indistinguishable from one that
+       never saw them, and the rule reference is what makes the derivation
+       observable rather than asserted. */
+    for (const path of excluded) {
+        process.stdout.write(`EXCLUDED ${path} ${renderRule(ephemeral.get(path))}\n`);
+    }
+    if (durable.length === 0) {
+        process.stdout.write("NOTHING TO COMMIT\n");
+    }
+    else {
+        const added = runGit(fleet.root, ["add", "--", ...durable]);
+        if (added.status !== 0) {
+            process.stderr.write(`tiphys sync: git add failed in ${fleet.root}: ${added.stderr.split("\n")[0] ?? ""}\n`);
+            return 1;
+        }
+        const committed = runGit(fleet.root, ["commit", "-m", syncCommitMessage(durable.length)], {
+            /* The documented deterministic machine identity, command-scoped,
+               exactly as the bootstrap commit does it: CI runners have no git
+               identity and this must never touch user or global config
+               (CLAUDE.md standing warning 5). */
+            extraEnv: {
+                GIT_AUTHOR_NAME: MACHINE_IDENTITY_NAME,
+                GIT_AUTHOR_EMAIL: MACHINE_IDENTITY_EMAIL,
+                GIT_COMMITTER_NAME: MACHINE_IDENTITY_NAME,
+                GIT_COMMITTER_EMAIL: MACHINE_IDENTITY_EMAIL,
+            },
+        });
+        if (committed.status !== 0) {
+            process.stderr.write(`tiphys sync: git commit failed in ${fleet.root}: ${committed.stderr.split("\n")[0] ?? ""}\n`);
+            return 1;
+        }
+        for (const path of durable) {
+            process.stdout.write(`COMMITTED ${path}\n`);
+        }
+    }
+    /* THE PUSH ARM IS NOT OPTIONAL AND ITS FAILURE IS NOT A WARNING. The
+       failure carries GIT'S OWN first stderr line rather than a message
+       composed here: a retry signature or a diagnosis derived from a
+       hand-written example is the failure T-003 and CLAUDE.md standing warning
+       10 both record. */
+    const pushed = runGit(fleet.root, ["push", remote, "HEAD"]);
+    if (pushed.status !== 0) {
+        const first = pushed.stderr.split("\n")[0] ?? "";
+        process.stderr.write(`tiphys sync: git push to ${remote} exited ${String(pushed.status)}, ` +
+            `so the durable state is committed locally and NOT pushed: ${first}\n`);
+        return 1;
+    }
+    process.stdout.write(`PUSHED ${remote}\n`);
+    return 0;
+}

package/dist/src/commands/teardown.js

@@ -14,7 +14,7 @@ import { teardownTask } from "../teardown.js";
  * survivors are enumerated); this command adds no framing of its own to
  * either, because the two must never be described alike.
  */
-const USAGE = "usage: tiphys teardown --task <id> [--salvage]";
+const USAGE = "usage: tiphys teardown --task <id> [--salvage] [--from-reconstructed]";
 function usageError(message) {
     if (message !== undefined) {
         process.stderr.write(`tiphys teardown: ${message}\n`);
@@ -23,7 +23,11 @@ function usageError(message) {
     return EX_USAGE;
 }
 function parseFlags(args) {
-    const parsed = { task: undefined, salvage: false };
+    const parsed = {
+        task: undefined,
+        salvage: false,
+        fromReconstructed: false,
+    };
     for (let i = 0; i < args.length; i += 1) {
         const flag = args[i];
         const value = args[i + 1];
@@ -34,6 +38,9 @@ function parseFlags(args) {
         else if (flag === "--salvage") {
             parsed.salvage = true;
         }
+        else if (flag === "--from-reconstructed") {
+            parsed.fromReconstructed = true;
+        }
         else {
             return undefined;
         }
@@ -64,6 +71,7 @@ export async function cmdTeardown(args) {
     const result = await teardownTask(fleet, {
         taskId: flags.task,
         salvage: flags.salvage,
+        fromReconstructed: flags.fromReconstructed,
     });
     if (!result.ok) {
         // Plan step 5: "every refusal is exit nonzero plus a single reason