@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/exec/env.d.ts

@@ -61,6 +61,152 @@
  * knows, it does not replace this allowlist.
  */
 export declare const DEFAULT_CHILD_ENV_ALLOWLIST: readonly string[];
+/**
+ * ONE PER-INVOCATION ALLOWLIST EXTENSION, AND THE REASON IT WAS GRANTED
+ * (M4-P8 step 3). The reason is DATA, not a comment beside the call site:
+ * a widening whose justification lives in a source comment is invisible to
+ * the record a later reader opens, and "an extension with no recorded
+ * reason" is one of this phase's declared hazard items. An empty reason is
+ * therefore a REFUSAL and never a permitted shorthand.
+ */
+export interface ChildEnvExtension {
+    /** Exact variable name, same semantics as a default-allowlist entry. */
+    name: string;
+    /** Why this invocation may carry it. Non-empty; blank is refused. */
+    reason: string;
+}
+/**
+ * What an extension entry may be written as.
+ *
+ * THE BARE STRING IS THE PRE-M4-P8 FORM AND IT IS KEPT DELIBERATELY. The
+ * field has existed since M2-P8 as `readonly string[]` and the kernel's own
+ * tests model a widened allowlist with it (test/credentials-gate.test.ts).
+ * A string carries NO reason, so it cannot carry the audit half; both forms
+ * are refused identically for a dangerous NAME, which is the safety half.
+ *
+ * THE SENTENCE THAT USED TO STAND HERE WAS FALSE AND IS WITHDRAWN. It said a
+ * bare string "cannot satisfy the audited route: the route's entry point is
+ * `SpawnOptions.extraAllowlist`, which is typed `ChildEnvExtension[]` and
+ * cannot express one", and delivery/work-history/m4-p8.md item 8 repeated it.
+ * That is a COMPILE-TIME argument about a RUNTIME seam, and the same phase
+ * rejected exactly that argument one field over: test/payload-credentials.ts
+ * records that "the consumer that reaches this seam is a JavaScript plugin,
+ * and a missing field there is `undefined`, not a compile error". A clean-room
+ * review reproduced both a bare string and `{name}` with no `reason` crossing
+ * into a project payload through `spawnTask` (CR-B-002, HIGH), and this round
+ * re-reproduced both before changing anything. A type is not a guard at a seam
+ * a plugin reaches, and `refuseExtraAllowlist` with `reason-required` is the
+ * guard.
+ */
+export type ChildEnvExtensionEntry = string | ChildEnvExtension;
+/** The variable name an entry names, whichever form it is written in. */
+export declare function extensionName(entry: ChildEnvExtensionEntry): string;
+/** The recorded reason, or undefined for the bare-string form. */
+export declare function extensionReason(entry: ChildEnvExtensionEntry): string | undefined;
+/**
+ * WHETHER THIS CALLER DEMANDS A RECORDED REASON.
+ *
+ * NO DEFAULT, DELIBERATELY. A default here would be the very shape
+ * CR-B-002 is: an omitted argument silently taking the permissive arm.
+ * Every call site says which contract it is enforcing, and the two that
+ * exist say different things for reasons written at each of them.
+ */
+export type ReasonRequirement = "reason-required" | "reason-optional";
+/**
+ * REFUSE AN EXTENSION THE CHILD MUST NOT CARRY (M4-P8 step 4, criteria 3
+ * and 4).
+ *
+ * Until this phase `buildChildEnv` spread the extension into the copy loop
+ * unconditionally, so an extension naming `GH_TOKEN` crossed into a child
+ * and the `credential-scrub` gate stayed green, because that gate builds
+ * its OWN environment with no extension and probes the CONSTRUCTION rather
+ * than a real spawn. The allowlist is still the defense and it gains no
+ * name here; what this adds is that WIDENING it per invocation is checked
+ * against the same vocabulary the gate walks.
+ *
+ * ONE VOCABULARY, NOT TWO. `refusedEnvVocabulary`
+ * are IMPORTED from src/gates/credentials.ts rather than copied here or
+ * moved: plan step 4 offers move-or-re-export and requires the choice be
+ * recorded, and duplicating the walked vocabulary would create two lists
+ * that drift silently in the direction that matters. The import makes
+ * src/exec/env.ts and src/gates/credentials.ts a cycle, which is this
+ * repository's existing shape rather than a new one (thirteen cycles in
+ * `src/` at this branch's merge base, one of them src/spawn.ts to
+ * src/adapters/load.ts and back). The one rule the cycle imposes: NOTHING
+ * in this module may read an imported binding at module-evaluation time,
+ * only inside a function body, or the module loaded second hits the
+ * temporal dead zone. `test/payload-credentials.test.ts` imports both
+ * modules in both orders so that rule is checked rather than remembered.
+ *
+ * THE NAME CHECK IS ORDERED FIRST: a refused name is refused whatever reason
+ * accompanies it, so a persuasive reason can never buy a credential into a
+ * child.
+ *
+ * IT WALKS A DECLARED LIST OF VOCABULARIES, NOT A HAND-PICKED PAIR, AND THAT
+ * IS THE WHOLE OF CH-001 (clean-room-final-credential-hazard, HIGH) WITH
+ * CR-F-CRED-003 AND CR-F-CRED-004 (LOW) UNDER IT.
+ *
+ * Until this round the guard read two literal arms, `GH_TOKEN_VARIABLES` and
+ * `isDangerousEnvName`. src/gates/credentials.ts held a THIRD vocabulary,
+ * `EGRESS_ENV_VOCABULARY`, added by M4-P29 after that container measured
+ * `HTTPS_PROXY` as the single variable turning `api.github.com/user` from
+ * HTTP 403 into HTTP 200 inside a scrubbed child. The two arms could not see
+ * it, so the audited route ACCEPTED an extension naming the one variable this
+ * repository had twice measured to grant real GitHub reach, and it accepted
+ * `SSH_AUTH_SOCK`, an agent socket, because that sat in neither list either.
+ *
+ * The mechanism is general and is why the repair is not a third `if`: adding
+ * a vocabulary to the module that owns them left every consumer's coverage
+ * UNCHANGED AND SILENT, so a subset could only ever be found by probing a
+ * name. This walks `REFUSED_CHILD_ENV_VOCABULARIES`, which is that module's
+ * declared list of its own vocabularies, through `refusedEnvVocabulary`. A
+ * fourth vocabulary is walked here the moment it gains a row there, and
+ * test/payload-credentials.test.ts reddens on a `*_VOCABULARY` or
+ * `*_VARIABLES` export with no row.
+ *
+ * DR-0048 is the decision behind the egress half and it is not re-litigated
+ * here: the default scrubbed child carries seven names and no proxy, so
+ * refusing an egress extension withdraws nothing the design granted.
+ *
+ * THE REASON CHECK IS WRITTEN AS A POSITIVE VALIDITY TEST, AND THAT IS THE
+ * WHOLE OF FINDING CR-B-002 (clean-room-retro-B-criteria, HIGH).
+ *
+ * Until this round the guard read
+ * `reason !== undefined && reason.trim().length === 0`, which fires only on
+ * a PRESENT-but-blank reason. `extensionReason` returns `undefined` for a
+ * bare string entry and for an object with no `reason` property, so the
+ * first conjunct excused the absent case and the entry was ACCEPTED. The
+ * mechanism is general: a refusal predicate whose condition requires the
+ * value to be PRESENT leaves ABSENT unchecked, and the field this module's
+ * own doc comment calls mandatory ("every entry carries an exact name and a
+ * reason") is exactly the kind of field that reaches it as `undefined`.
+ *
+ * The repair is the spelling this repository already uses where it got this
+ * right: compute a POSITIVE `usable` predicate (src/cutover.ts:140 is the
+ * same shape, and `extensionName`'s `typeof name !== "string"` test two
+ * refusals above is the same shape again), then decide what to do with
+ * `!usable`. Absent, blank and non-string all reach `!usable` by different
+ * routes and the refusal SAYS which one it was, because an operator reading
+ * "carries no reason" about an entry that has one is looking for the wrong
+ * thing.
+ *
+ * `reasonRequirement` is what the two call sites differ on, and neither is
+ * a default:
+ *
+ *   reason-required   the AUDITED route (`checkCredentialPolicy` in
+ *                     src/spawn.ts). DR-0039 condition 2 and M4-P8
+ *                     criterion 4 are enforced here: an extension with no
+ *                     usable reason is refused before anything is created.
+ *   reason-optional   `buildChildEnv`, the pre-M4-P8 library seam, which
+ *                     documents the bare-string form and whose own tests
+ *                     model a widened allowlist with it. A blank reason is
+ *                     still refused there; an ABSENT one is the documented
+ *                     shorthand for "this caller records nothing", and the
+ *                     caller that must not be allowed that shorthand does
+ *                     not reach this module without passing through the
+ *                     audited route first.
+ */
+export declare function refuseExtraAllowlist(entries: readonly ChildEnvExtensionEntry[], reasonRequirement: ReasonRequirement): string | undefined;
 /** One redirected credential-store pointer. */
 export interface CredentialRedirection {
     /** The environment variable name. */
@@ -83,7 +229,7 @@ export declare function scrubRoot(taskDir: string): string;
  * Every variable name the constructed environment may contain: the
  * allowlist, the per-invocation extension, and the redirected pointers.
  */
-export declare function permittedChildEnvNames(extraAllowlist?: readonly string[]): Set<string>;
+export declare function permittedChildEnvNames(extraAllowlist?: readonly ChildEnvExtensionEntry[]): Set<string>;
 export interface ChildEnvSpec {
     /** The environment the values are copied FROM (usually process.env). */
     parentEnv: Record<string, string | undefined>;
@@ -96,8 +242,12 @@ export interface ChildEnvSpec {
     /**
      * Per-invocation allowlist extension (step 9's only obligation to the
      * future). Exact names, same semantics as the default list.
+     *
+     * SINCE M4-P8 EVERY ENTRY IS CHECKED before anything is staged: see
+     * `refuseExtraAllowlist` for the two refusals and for why the bare-string
+     * form is still accepted here while the audited route cannot produce one.
      */
-    extraAllowlist?: readonly string[];
+    extraAllowlist?: readonly ChildEnvExtensionEntry[];
 }
 export type ChildEnvResult = {
     ok: true;

package/dist/src/exec/env.js

@@ -1,5 +1,6 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { refusedEnvVocabulary } from "../gates/credentials.js";
 import { refuseOpenForWrite, runStep } from "../task.js";
 /**
  * CHILD-ENVIRONMENT CONSTRUCTION (kernel plan M2, M2-P8 steps 2 and 3).
@@ -90,6 +91,136 @@ export const DEFAULT_CHILD_ENV_ALLOWLIST = [
     "GIT_COMMITTER_EMAIL",
     "GIT_COMMITTER_DATE",
 ];
+/** The variable name an entry names, whichever form it is written in. */
+export function extensionName(entry) {
+    return typeof entry === "string" ? entry : entry.name;
+}
+/** The recorded reason, or undefined for the bare-string form. */
+export function extensionReason(entry) {
+    return typeof entry === "string" ? undefined : entry.reason;
+}
+/**
+ * REFUSE AN EXTENSION THE CHILD MUST NOT CARRY (M4-P8 step 4, criteria 3
+ * and 4).
+ *
+ * Until this phase `buildChildEnv` spread the extension into the copy loop
+ * unconditionally, so an extension naming `GH_TOKEN` crossed into a child
+ * and the `credential-scrub` gate stayed green, because that gate builds
+ * its OWN environment with no extension and probes the CONSTRUCTION rather
+ * than a real spawn. The allowlist is still the defense and it gains no
+ * name here; what this adds is that WIDENING it per invocation is checked
+ * against the same vocabulary the gate walks.
+ *
+ * ONE VOCABULARY, NOT TWO. `refusedEnvVocabulary`
+ * are IMPORTED from src/gates/credentials.ts rather than copied here or
+ * moved: plan step 4 offers move-or-re-export and requires the choice be
+ * recorded, and duplicating the walked vocabulary would create two lists
+ * that drift silently in the direction that matters. The import makes
+ * src/exec/env.ts and src/gates/credentials.ts a cycle, which is this
+ * repository's existing shape rather than a new one (thirteen cycles in
+ * `src/` at this branch's merge base, one of them src/spawn.ts to
+ * src/adapters/load.ts and back). The one rule the cycle imposes: NOTHING
+ * in this module may read an imported binding at module-evaluation time,
+ * only inside a function body, or the module loaded second hits the
+ * temporal dead zone. `test/payload-credentials.test.ts` imports both
+ * modules in both orders so that rule is checked rather than remembered.
+ *
+ * THE NAME CHECK IS ORDERED FIRST: a refused name is refused whatever reason
+ * accompanies it, so a persuasive reason can never buy a credential into a
+ * child.
+ *
+ * IT WALKS A DECLARED LIST OF VOCABULARIES, NOT A HAND-PICKED PAIR, AND THAT
+ * IS THE WHOLE OF CH-001 (clean-room-final-credential-hazard, HIGH) WITH
+ * CR-F-CRED-003 AND CR-F-CRED-004 (LOW) UNDER IT.
+ *
+ * Until this round the guard read two literal arms, `GH_TOKEN_VARIABLES` and
+ * `isDangerousEnvName`. src/gates/credentials.ts held a THIRD vocabulary,
+ * `EGRESS_ENV_VOCABULARY`, added by M4-P29 after that container measured
+ * `HTTPS_PROXY` as the single variable turning `api.github.com/user` from
+ * HTTP 403 into HTTP 200 inside a scrubbed child. The two arms could not see
+ * it, so the audited route ACCEPTED an extension naming the one variable this
+ * repository had twice measured to grant real GitHub reach, and it accepted
+ * `SSH_AUTH_SOCK`, an agent socket, because that sat in neither list either.
+ *
+ * The mechanism is general and is why the repair is not a third `if`: adding
+ * a vocabulary to the module that owns them left every consumer's coverage
+ * UNCHANGED AND SILENT, so a subset could only ever be found by probing a
+ * name. This walks `REFUSED_CHILD_ENV_VOCABULARIES`, which is that module's
+ * declared list of its own vocabularies, through `refusedEnvVocabulary`. A
+ * fourth vocabulary is walked here the moment it gains a row there, and
+ * test/payload-credentials.test.ts reddens on a `*_VOCABULARY` or
+ * `*_VARIABLES` export with no row.
+ *
+ * DR-0048 is the decision behind the egress half and it is not re-litigated
+ * here: the default scrubbed child carries seven names and no proxy, so
+ * refusing an egress extension withdraws nothing the design granted.
+ *
+ * THE REASON CHECK IS WRITTEN AS A POSITIVE VALIDITY TEST, AND THAT IS THE
+ * WHOLE OF FINDING CR-B-002 (clean-room-retro-B-criteria, HIGH).
+ *
+ * Until this round the guard read
+ * `reason !== undefined && reason.trim().length === 0`, which fires only on
+ * a PRESENT-but-blank reason. `extensionReason` returns `undefined` for a
+ * bare string entry and for an object with no `reason` property, so the
+ * first conjunct excused the absent case and the entry was ACCEPTED. The
+ * mechanism is general: a refusal predicate whose condition requires the
+ * value to be PRESENT leaves ABSENT unchecked, and the field this module's
+ * own doc comment calls mandatory ("every entry carries an exact name and a
+ * reason") is exactly the kind of field that reaches it as `undefined`.
+ *
+ * The repair is the spelling this repository already uses where it got this
+ * right: compute a POSITIVE `usable` predicate (src/cutover.ts:140 is the
+ * same shape, and `extensionName`'s `typeof name !== "string"` test two
+ * refusals above is the same shape again), then decide what to do with
+ * `!usable`. Absent, blank and non-string all reach `!usable` by different
+ * routes and the refusal SAYS which one it was, because an operator reading
+ * "carries no reason" about an entry that has one is looking for the wrong
+ * thing.
+ *
+ * `reasonRequirement` is what the two call sites differ on, and neither is
+ * a default:
+ *
+ *   reason-required   the AUDITED route (`checkCredentialPolicy` in
+ *                     src/spawn.ts). DR-0039 condition 2 and M4-P8
+ *                     criterion 4 are enforced here: an extension with no
+ *                     usable reason is refused before anything is created.
+ *   reason-optional   `buildChildEnv`, the pre-M4-P8 library seam, which
+ *                     documents the bare-string form and whose own tests
+ *                     model a widened allowlist with it. A blank reason is
+ *                     still refused there; an ABSENT one is the documented
+ *                     shorthand for "this caller records nothing", and the
+ *                     caller that must not be allowed that shorthand does
+ *                     not reach this module without passing through the
+ *                     audited route first.
+ */
+export function refuseExtraAllowlist(entries, reasonRequirement) {
+    for (const entry of entries) {
+        const name = extensionName(entry);
+        if (typeof name !== "string" || name.length === 0) {
+            return (`an allowlist extension entry names no variable ` +
+                `(${JSON.stringify(entry)}); every entry carries an exact name and a reason`);
+        }
+        const refusedBy = refusedEnvVocabulary(name);
+        if (refusedBy !== undefined) {
+            return `the allowlist extension entry ${name} ${refusedBy.clause}`;
+        }
+        const reason = extensionReason(entry);
+        const usable = typeof reason === "string" && reason.trim().length > 0;
+        if (!usable) {
+            const shape = reason === undefined
+                ? "no reason field at all"
+                : typeof reason !== "string"
+                    ? `a reason that is not a string (${JSON.stringify(reason)})`
+                    : `a blank reason (${JSON.stringify(reason)})`;
+            if (reasonRequirement === "reason-required" || reason !== undefined) {
+                return (`the allowlist extension entry ${name} carries ${shape}; an extension ` +
+                    `is an audited widening and a reason that is absent, blank or not a ` +
+                    `string records nothing a later reader could check`);
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * The five pointers, redirected in this order. Each names a credential
  * store's location; see the module comment for why none may be dropped.
@@ -114,7 +245,7 @@ export function scrubRoot(taskDir) {
 export function permittedChildEnvNames(extraAllowlist = []) {
     return new Set([
         ...DEFAULT_CHILD_ENV_ALLOWLIST,
-        ...extraAllowlist,
+        ...extraAllowlist.map(extensionName),
         ...CREDENTIAL_STORE_REDIRECTIONS.map((redirection) => redirection.name),
         "GIT_CONFIG_NOSYSTEM",
     ]);
@@ -139,6 +270,19 @@ export function permittedChildEnvNames(extraAllowlist = []) {
  * credential path, so there is no partial success here (fail closed).
  */
 export function buildChildEnv(spec) {
+    // THE EXTENSION IS CHECKED FIRST, BEFORE ANY DIRECTORY IS MADE (M4-P8
+    // criteria 3 and 4). A refusal that had already staged a scrub root would
+    // leave the caller's rollback holding something this call created, and
+    // the whole point of refusing here is that a rejected widening costs
+    // nothing and changes nothing.
+    // `reason-optional`, and the argument is passed rather than defaulted: see
+    // `ReasonRequirement`. This seam predates M4-P8 and documents the
+    // bare-string form; the audited route demands a reason one layer up, in
+    // `checkCredentialPolicy`, before anything is created.
+    const refusal = refuseExtraAllowlist(spec.extraAllowlist ?? [], "reason-optional");
+    if (refusal !== undefined) {
+        return { ok: false, reason: refusal };
+    }
     const made = runStep(`creating the scrub root ${spec.scrubDir}`, () => mkdirSync(spec.scrubDir, { recursive: true }));
     if (!made.ok) {
         return { ok: false, reason: made.reason };
@@ -146,7 +290,7 @@ export function buildChildEnv(spec) {
     const env = {};
     const names = [
         ...DEFAULT_CHILD_ENV_ALLOWLIST,
-        ...(spec.extraAllowlist ?? []),
+        ...(spec.extraAllowlist ?? []).map(extensionName),
     ];
     for (const name of names) {
         const value = spec.parentEnv[name];

package/dist/src/fleet.d.ts

@@ -49,3 +49,175 @@ export declare function missingLayoutEntries(dir: string): string[];
  * naming every missing entry when the layout is incomplete.
  */
 export declare function loadFleet(dir: string): Fleet;
+/**
+ * A layout entry's type, established BEFORE anything is done with the path.
+ * `classifyEntry` in src/task.ts answers "may this be opened as a regular
+ * file" and therefore calls a directory irregular, which is the wrong answer
+ * for a layout entry: here a directory is the wanted shape. Same discipline,
+ * different question, so it is a separate function rather than a flag on that
+ * one (plan constraint C-2 is unaffected; nothing here probes a process).
+ */
+export type LayoutEntryClass = 
+/** Nothing at the path. */
+{
+    kind: "absent";
+}
+/** A directory, or a symlink resolving to one. */
+ | {
+    kind: "directory";
+}
+/** Present and not a directory, or a symlink resolving to nothing. */
+ | {
+    kind: "other";
+    reason: string;
+}
+/** Neither lstat nor stat could answer the question. */
+ | {
+    kind: "unexaminable";
+    reason: string;
+};
+/**
+ * Classify a layout path without opening it. lstat first, so a symlink is
+ * seen as a symlink; then stat, so a symlink to a directory is a directory
+ * and a dangling one is reported as such rather than as absent.
+ */
+export declare function classifyLayoutEntry(path: string): LayoutEntryClass;
+/**
+ * The EPHEMERAL directories: exactly the gitignored set, with the trailing
+ * slash that `.gitignore` needs stripped off. DERIVED from FLEET_IGNORED
+ * rather than listed again, because a second list is a second thing to keep
+ * in step and the first divergence would be silent: `tiphys resume` would
+ * rebuild one set while `.gitignore` ignored another.
+ */
+export declare const EPHEMERAL_DIRS: readonly string[];
+/**
+ * The DURABLE directories: every fleet directory that is not ephemeral.
+ * A clone of a fleet home carries these and not the ephemeral ones, which
+ * is the fact `tiphys resume` exists to act on.
+ */
+export declare const DURABLE_DIRS: readonly string[];
+/**
+ * The durable layout entries missing from dir, in declaration order:
+ * directories first with a trailing slash, then the root files. An empty
+ * result means the directory carries everything a clone of a fleet home
+ * carries, which is the precondition `tiphys resume` requires and never
+ * fabricates.
+ */
+export declare function missingDurableEntries(dir: string): string[];
+/**
+ * THE GUARDED OPEN, AT THE BOTTOM OF THE IMPORT GRAPH.
+ *
+ * `classifyEntry` in src/task.ts:118 asks exactly this question and its own
+ * docblock says where it belongs: "a general filesystem rule and not a task
+ * rule, and a dedicated module would be its right home. This module is the
+ * lowest one in the import graph that the fix round authorized to touch."
+ * This module is LOWER. src/task.ts imports src/lock.ts, src/lock.ts imports
+ * src/exclusion.ts, and this file imports nothing from the project at all, so
+ * the two modules that hold the kernel's lease and register reads CANNOT
+ * reach src/task.ts without making the first import cycle in `src/` (measured
+ * at this head: the graph is a strict DAG). They reach these instead.
+ *
+ * THE DUPLICATION IS REAL AND IT IS NAMED RATHER THAN HIDDEN. Two
+ * implementations of one question can drift, and the end state is src/task.ts
+ * re-exporting these. That edit is not in this round's declared file set, so
+ * it is escalated rather than made, and until it happens the vocabulary, the
+ * branch order and the refusal TEXT below are kept identical to src/task.ts's
+ * on purpose: doctor already prints "is a named pipe, not a regular file, so
+ * it was not opened" for a lease, and a second sentence for the same state
+ * would make two true reports read as two different conditions.
+ *
+ * C-2 is unaffected: lstat and stat are questions about a directory entry,
+ * never about a running program.
+ */
+export type PathEntryClass = 
+/** Nothing at the path. */
+{
+    kind: "absent";
+}
+/** A link is there and resolves to nothing: it exists, and it is empty of evidence. */
+ | {
+    kind: "dangling";
+}
+/** Safe to open. */
+ | {
+    kind: "regular";
+}
+/** Present, and opening it is not safe: never opened, always named. */
+ | {
+    kind: "irregular";
+    reason: string;
+}
+/** Neither lstat nor stat could answer the question. */
+ | {
+    kind: "unexaminable";
+    reason: string;
+};
+/**
+ * lstat first, so a symlink is seen as a symlink; then stat, so a symlink to
+ * a regular file is regular and a dangling one is reported as such rather
+ * than as absent. The path is never opened.
+ */
+export declare function classifyPathEntry(path: string): PathEntryClass;
+/** What a guarded read of a possibly-absent path produced. */
+export type RegularPathRead = {
+    kind: "read";
+    body: string;
+} | {
+    kind: "absent";
+}
+/** Present and not readable, with a reason naming the path. */
+ | {
+    kind: "refused";
+    reason: string;
+};
+/** THE ONE READ of a path that might not be there and might not be a file. */
+export declare function readRegularPathIfPresent(path: string): RegularPathRead;
+/**
+ * Refuse an open-for-WRITE of a path that is not a regular file. The hazard
+ * is symmetric: open(2) for writing on a FIFO with no reader blocks exactly
+ * as reading one with no writer does, so a staged write is as dangerous as a
+ * read. Returns the reason, or undefined when the path may be opened (absent
+ * included: creating it is the point).
+ */
+export declare function refuseOpenPathForWrite(path: string): string | undefined;
+/**
+ * THE KERNEL'S OWN WRITE-THEN-RENAME SCRATCH SUFFIXES.
+ *
+ * `FLEET_IGNORED` above is a DENYLIST of three directory prefixes, and
+ * `tiphys sync` derives "durable" as "not covered by it". That derivation is
+ * right for everything the ignore rules were written to cover and blind to a
+ * class they were never asked about: a transient artifact the KERNEL ITSELF
+ * creates beside a TRACKED target, which git therefore reports as an
+ * ordinary new durable path.
+ *
+ * The enumeration behind this list is every path the kernel writes under a
+ * fleet home, classified against `FLEET_IGNORED`. The three that land
+ * DURABLE without being fleet content are:
+ *
+ *   status/current.json.tmp     src/status.ts:142, a fixed name inside the
+ *                               tracked status/ directory.
+ *   .cutover.<random>.tmp       src/cutover.ts:278, a dot-prefixed random
+ *                               name at the fleet ROOT.
+ *   tiphys-environment.json     src/exclusion.ts:303, durable ON PURPOSE
+ *                               (M4-P21 criterion 3) and therefore NOT in
+ *                               this list.
+ *
+ * Two members, two directories, two naming shapes, which is why the rule is
+ * a SUFFIX and not a filename: a rule naming `current.json.tmp` would close
+ * the first and leave the second open.
+ *
+ * `FLEET_IGNORED` IS DELIBERATELY UNCHANGED. It drives `EPHEMERAL_DIRS`,
+ * `DURABLE_DIRS` and the `.gitignore` that `tiphys init` writes, so a glob
+ * added there would become a directory name `tiphys resume` tried to rebuild.
+ * Nothing stops being synced because of this constant; `tiphys sync` gains a
+ * refusal, and only for paths matching a suffix below.
+ */
+export declare const FLEET_SCRATCH_SUFFIXES: readonly string[];
+/**
+ * True when a fleet-relative path is a kernel scratch artifact by its name
+ * alone. Name-only on purpose: `tiphys sync` asks this about a path git
+ * REPORTED, which may already have been renamed away by the time the
+ * question is asked, so a stat here would answer about a different world
+ * than the one being committed.
+ */
+export declare function isFleetScratchPath(relativePath: string): string | undefined;