@tiphys/kernel 0.0.0 → 0.1.0

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

@@ -0,0 +1,128 @@
+/**
+ * CHILD-ENVIRONMENT CONSTRUCTION (kernel plan M2, M2-P8 steps 2 and 3).
+ *
+ * Every child the executor launches (the payload and the turn-end hook)
+ * receives an environment BUILT here, never inherited. The build is an
+ * ALLOWLIST (M2-D-13): a variable crosses into the child only when its
+ * exact name is in the list below or in the caller's per-invocation
+ * extension. There is no denylist anywhere in this module, because a
+ * denylist is a union of the credential names known on the day it was
+ * written and grows stale silently; an allowlist fails in the safe
+ * direction (a missing variable is a visible breakage, a leaked one is
+ * not).
+ *
+ * REDIRECT, NEVER DROP, THE CREDENTIAL-STORE POINTERS (M2R-004 edit 1).
+ * `HOME`, `XDG_CONFIG_HOME`, `GH_CONFIG_DIR`, `GIT_CONFIG_GLOBAL` and
+ * `GIT_CONFIG_SYSTEM` are not simply excluded from the allowlist; they are
+ * SET to harness-owned empty paths inside the task directory. Dropping any
+ * of them is FORBIDDEN, and this comment is the record of why:
+ *
+ *   - A dropped `HOME` does not remove the home directory; the child's
+ *     tools fall back to the real one (or to `/root`), so gh resolves
+ *     `$HOME/.config/gh/hosts.yml`, git resolves `~/.gitconfig`,
+ *     `~/.netrc` and `~/.git-credentials`, and every default credential
+ *     path RETURNS. An environment-only scrub that drops pointers leaves
+ *     the credential stores in place, which is exactly finding M2R-004.
+ *   - A dropped `GIT_CONFIG_GLOBAL` additionally hands the child the
+ *     user's real global git configuration, undoing the EXT-F-02
+ *     discipline (v1 M1-P2 criterion 7): the kernel never reads and never
+ *     writes user or global git config, and commit identity crosses as
+ *     command-scoped GIT_AUTHOR_* / GIT_COMMITTER_* variables only.
+ *
+ * THE ALLOWLIST IS DATA, NOT A LITERAL INSIDE A SPAWN CALL (step 9). It is
+ * exported and `buildChildEnv` takes a per-invocation `extraAllowlist`, so
+ * a future caller (the M4-era release-verification wiring designed in
+ * delivery/verification/release-verification-interface.md section 6.1)
+ * can extend it per invocation and per adapter without touching this
+ * module. Nothing in this module knows about release verification; that
+ * is deliberate and this phase builds no such awareness.
+ *
+ * WHY THE THREE TIPHYS_EXIT_TEST_* NAMES ARE HERE. The delivered payload
+ * contract (scripts/stub-payload.sh, its documented environment contract)
+ * is the one place variables cross the spawn boundary into a payload
+ * today, and it names exactly these three. They are listed as exact names
+ * rather than as a TIPHYS_* prefix on purpose: a prefix rule would carry
+ * ANY variable that happens to start with TIPHYS_, which is a denylist's
+ * failure mode wearing an allowlist's name (and is what acceptance
+ * criterion 2's TIPHYS_UNRELATED_SECRET witness refutes).
+ */
+/**
+ * The default allowlist. Exact names only; no prefixes, no patterns.
+ * Append here only with a recorded reason, and never a credential-capable
+ * name. This allowlist is the REAL defense: a name crosses only if it is
+ * here (or in a per-invocation extension), so nothing outside it appears
+ * in a child by construction. `credential-scrub` (src/gates/credentials.ts)
+ * adds a bounded, allowlist-INDEPENDENT tripwire on top: it reddens if a
+ * gh-documented token variable OR a git/ssh/node credential- or
+ * code-execution-capable variable (its documented vocabulary) is present
+ * in the constructed child, even if some future edit wrongly adds one
+ * here. That tripwire is a bounded denylist and cannot enumerate every
+ * dangerous name; it makes a widened allowlist cost a red for the names it
+ * knows, it does not replace this allowlist.
+ */
+export declare const DEFAULT_CHILD_ENV_ALLOWLIST: readonly string[];
+/** One redirected credential-store pointer. */
+export interface CredentialRedirection {
+    /** The environment variable name. */
+    name: string;
+    /** Whether the harness-owned target is a directory or a file. */
+    kind: "directory" | "file";
+    /** Path of the target relative to the scrub root. */
+    relativePath: string;
+}
+/**
+ * The five pointers, redirected in this order. Each names a credential
+ * store's location; see the module comment for why none may be dropped.
+ */
+export declare const CREDENTIAL_STORE_REDIRECTIONS: readonly CredentialRedirection[];
+/** Directory name of the scrub root inside a task directory. */
+export declare const SCRUB_DIR_NAME = "scrub-env";
+/** Where spawn puts the harness-owned redirect targets for a task. */
+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 interface ChildEnvSpec {
+    /** The environment the values are copied FROM (usually process.env). */
+    parentEnv: Record<string, string | undefined>;
+    /**
+     * Absolute path of the harness-owned scrub root. Created (with its five
+     * redirect targets) by this call; must sit inside a directory this
+     * invocation owns, which for spawn is the task directory.
+     */
+    scrubDir: string;
+    /**
+     * Per-invocation allowlist extension (step 9's only obligation to the
+     * future). Exact names, same semantics as the default list.
+     */
+    extraAllowlist?: readonly string[];
+}
+export type ChildEnvResult = {
+    ok: true;
+    env: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Build the child environment: create the scrub root and its five EMPTY
+ * redirect targets, copy the allowlisted names that are present in the
+ * parent environment, then OVERRIDE the five pointers with the
+ * harness-owned paths. The override runs last and unconditionally, so a
+ * pointer that is also (wrongly) allowlisted still ends up redirected.
+ *
+ * EVERY redirect target is re-emptied on every build, directory and file
+ * alike: a leftover store file from a prior same-taskId incarnation (a
+ * .git-credentials or hosts.yml written into a directory target, or a
+ * populated gitconfig-global file) must not survive a rebuild and smuggle
+ * configuration into the next child (M2-P8 fix round 1, review finding O1).
+ * File targets are rewritten empty; directory targets are removed and
+ * recreated so they are empty too.
+ *
+ * A failure to stage any redirect target fails the whole construction:
+ * an unredirected pointer would silently fall back to the default
+ * credential path, so there is no partial success here (fail closed).
+ */
+export declare function buildChildEnv(spec: ChildEnvSpec): ChildEnvResult;

package/dist/src/exec/env.js

@@ -0,0 +1,190 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { refuseOpenForWrite, runStep } from "../task.js";
+/**
+ * CHILD-ENVIRONMENT CONSTRUCTION (kernel plan M2, M2-P8 steps 2 and 3).
+ *
+ * Every child the executor launches (the payload and the turn-end hook)
+ * receives an environment BUILT here, never inherited. The build is an
+ * ALLOWLIST (M2-D-13): a variable crosses into the child only when its
+ * exact name is in the list below or in the caller's per-invocation
+ * extension. There is no denylist anywhere in this module, because a
+ * denylist is a union of the credential names known on the day it was
+ * written and grows stale silently; an allowlist fails in the safe
+ * direction (a missing variable is a visible breakage, a leaked one is
+ * not).
+ *
+ * REDIRECT, NEVER DROP, THE CREDENTIAL-STORE POINTERS (M2R-004 edit 1).
+ * `HOME`, `XDG_CONFIG_HOME`, `GH_CONFIG_DIR`, `GIT_CONFIG_GLOBAL` and
+ * `GIT_CONFIG_SYSTEM` are not simply excluded from the allowlist; they are
+ * SET to harness-owned empty paths inside the task directory. Dropping any
+ * of them is FORBIDDEN, and this comment is the record of why:
+ *
+ *   - A dropped `HOME` does not remove the home directory; the child's
+ *     tools fall back to the real one (or to `/root`), so gh resolves
+ *     `$HOME/.config/gh/hosts.yml`, git resolves `~/.gitconfig`,
+ *     `~/.netrc` and `~/.git-credentials`, and every default credential
+ *     path RETURNS. An environment-only scrub that drops pointers leaves
+ *     the credential stores in place, which is exactly finding M2R-004.
+ *   - A dropped `GIT_CONFIG_GLOBAL` additionally hands the child the
+ *     user's real global git configuration, undoing the EXT-F-02
+ *     discipline (v1 M1-P2 criterion 7): the kernel never reads and never
+ *     writes user or global git config, and commit identity crosses as
+ *     command-scoped GIT_AUTHOR_* / GIT_COMMITTER_* variables only.
+ *
+ * THE ALLOWLIST IS DATA, NOT A LITERAL INSIDE A SPAWN CALL (step 9). It is
+ * exported and `buildChildEnv` takes a per-invocation `extraAllowlist`, so
+ * a future caller (the M4-era release-verification wiring designed in
+ * delivery/verification/release-verification-interface.md section 6.1)
+ * can extend it per invocation and per adapter without touching this
+ * module. Nothing in this module knows about release verification; that
+ * is deliberate and this phase builds no such awareness.
+ *
+ * WHY THE THREE TIPHYS_EXIT_TEST_* NAMES ARE HERE. The delivered payload
+ * contract (scripts/stub-payload.sh, its documented environment contract)
+ * is the one place variables cross the spawn boundary into a payload
+ * today, and it names exactly these three. They are listed as exact names
+ * rather than as a TIPHYS_* prefix on purpose: a prefix rule would carry
+ * ANY variable that happens to start with TIPHYS_, which is a denylist's
+ * failure mode wearing an allowlist's name (and is what acceptance
+ * criterion 2's TIPHYS_UNRELATED_SECRET witness refutes).
+ */
+/**
+ * The default allowlist. Exact names only; no prefixes, no patterns.
+ * Append here only with a recorded reason, and never a credential-capable
+ * name. This allowlist is the REAL defense: a name crosses only if it is
+ * here (or in a per-invocation extension), so nothing outside it appears
+ * in a child by construction. `credential-scrub` (src/gates/credentials.ts)
+ * adds a bounded, allowlist-INDEPENDENT tripwire on top: it reddens if a
+ * gh-documented token variable OR a git/ssh/node credential- or
+ * code-execution-capable variable (its documented vocabulary) is present
+ * in the constructed child, even if some future edit wrongly adds one
+ * here. That tripwire is a bounded denylist and cannot enumerate every
+ * dangerous name; it makes a widened allowlist cost a red for the names it
+ * knows, it does not replace this allowlist.
+ */
+export const DEFAULT_CHILD_ENV_ALLOWLIST = [
+    // Program resolution and scratch space.
+    "PATH",
+    "TMPDIR",
+    // Locale, so a child's tool output is not re-localised mid-suite.
+    "LANG",
+    "LANGUAGE",
+    "LC_ALL",
+    "LC_COLLATE",
+    "LC_CTYPE",
+    "LC_MESSAGES",
+    "LC_MONETARY",
+    "LC_NUMERIC",
+    "LC_TIME",
+    // The payload contract of the exit-test harness (see module comment).
+    "TIPHYS_EXIT_TEST_MODE",
+    "TIPHYS_EXIT_TEST_TASK",
+    "TIPHYS_EXIT_TEST_REPORT",
+    // Command-scoped git identity (EXT-F-02 option B): the ONLY sanctioned
+    // way identity reaches a child, and never a credential.
+    "GIT_AUTHOR_NAME",
+    "GIT_AUTHOR_EMAIL",
+    "GIT_AUTHOR_DATE",
+    "GIT_COMMITTER_NAME",
+    "GIT_COMMITTER_EMAIL",
+    "GIT_COMMITTER_DATE",
+];
+/**
+ * The five pointers, redirected in this order. Each names a credential
+ * store's location; see the module comment for why none may be dropped.
+ */
+export const CREDENTIAL_STORE_REDIRECTIONS = [
+    { name: "HOME", kind: "directory", relativePath: "home" },
+    { name: "XDG_CONFIG_HOME", kind: "directory", relativePath: "xdg-config" },
+    { name: "GH_CONFIG_DIR", kind: "directory", relativePath: "gh-config" },
+    { name: "GIT_CONFIG_GLOBAL", kind: "file", relativePath: "gitconfig-global" },
+    { name: "GIT_CONFIG_SYSTEM", kind: "file", relativePath: "gitconfig-system" },
+];
+/** Directory name of the scrub root inside a task directory. */
+export const SCRUB_DIR_NAME = "scrub-env";
+/** Where spawn puts the harness-owned redirect targets for a task. */
+export function scrubRoot(taskDir) {
+    return join(taskDir, SCRUB_DIR_NAME);
+}
+/**
+ * Every variable name the constructed environment may contain: the
+ * allowlist, the per-invocation extension, and the redirected pointers.
+ */
+export function permittedChildEnvNames(extraAllowlist = []) {
+    return new Set([
+        ...DEFAULT_CHILD_ENV_ALLOWLIST,
+        ...extraAllowlist,
+        ...CREDENTIAL_STORE_REDIRECTIONS.map((redirection) => redirection.name),
+        "GIT_CONFIG_NOSYSTEM",
+    ]);
+}
+/**
+ * Build the child environment: create the scrub root and its five EMPTY
+ * redirect targets, copy the allowlisted names that are present in the
+ * parent environment, then OVERRIDE the five pointers with the
+ * harness-owned paths. The override runs last and unconditionally, so a
+ * pointer that is also (wrongly) allowlisted still ends up redirected.
+ *
+ * EVERY redirect target is re-emptied on every build, directory and file
+ * alike: a leftover store file from a prior same-taskId incarnation (a
+ * .git-credentials or hosts.yml written into a directory target, or a
+ * populated gitconfig-global file) must not survive a rebuild and smuggle
+ * configuration into the next child (M2-P8 fix round 1, review finding O1).
+ * File targets are rewritten empty; directory targets are removed and
+ * recreated so they are empty too.
+ *
+ * A failure to stage any redirect target fails the whole construction:
+ * an unredirected pointer would silently fall back to the default
+ * credential path, so there is no partial success here (fail closed).
+ */
+export function buildChildEnv(spec) {
+    const made = runStep(`creating the scrub root ${spec.scrubDir}`, () => mkdirSync(spec.scrubDir, { recursive: true }));
+    if (!made.ok) {
+        return { ok: false, reason: made.reason };
+    }
+    const env = {};
+    const names = [
+        ...DEFAULT_CHILD_ENV_ALLOWLIST,
+        ...(spec.extraAllowlist ?? []),
+    ];
+    for (const name of names) {
+        const value = spec.parentEnv[name];
+        if (value !== undefined) {
+            env[name] = value;
+        }
+    }
+    for (const redirection of CREDENTIAL_STORE_REDIRECTIONS) {
+        const target = join(spec.scrubDir, redirection.relativePath);
+        if (redirection.kind === "directory") {
+            // Re-empty the directory target on every build (remove then
+            // recreate), exactly as the file targets are rewritten empty below,
+            // so a leftover store file from an earlier incarnation cannot
+            // smuggle configuration in (review finding O1).
+            const cleared = runStep(`re-emptying the redirect target ${target}`, () => {
+                rmSync(target, { recursive: true, force: true });
+                mkdirSync(target, { recursive: true });
+            });
+            if (!cleared.ok) {
+                return { ok: false, reason: cleared.reason };
+            }
+        }
+        else {
+            // The file target is written EMPTY on every build, so a leftover
+            // from an earlier incarnation cannot smuggle configuration in.
+            const refusal = refuseOpenForWrite(target);
+            if (refusal !== undefined) {
+                return { ok: false, reason: refusal };
+            }
+            const written = runStep(`staging the empty redirect target ${target}`, () => writeFileSync(target, ""));
+            if (!written.ok) {
+                return { ok: false, reason: written.reason };
+            }
+        }
+        env[redirection.name] = target;
+    }
+    // Apple Git reads a prefix system config in addition to GIT_CONFIG_SYSTEM.
+    // This fixed kernel value is applied after copying and cannot be inherited.
+    env["GIT_CONFIG_NOSYSTEM"] = "1";
+    return { ok: true, env };
+}

package/dist/src/fleet.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Fleet-home layout (kernel plan v1, M1-P2 step 1; blueprint section 3 with
+ * the SC-002/SC-003 resolutions). The fleet home is a small git repository:
+ * durable content (charter/, decisions/, tasks/, backlog.md, package.json,
+ * .gitignore) is tracked; state/, worktrees/, and projects/ are ephemeral
+ * and gitignored (plan decision D-4, PR-004).
+ */
+export declare const FLEET_DIRS: readonly ["charter", "decisions", "state", "tasks", "worktrees", "projects"];
+/** Files every fleet home carries at its root. */
+export declare const FLEET_FILES: readonly ["backlog.md", "package.json", ".gitignore"];
+/**
+ * Exactly these entries are gitignored: clones under projects/ are
+ * recoverable from their remotes, worktrees/ are disposable, state/ holds
+ * beacons and locks (SC-002, plan decision D-4, PR-004). Nothing else.
+ */
+export declare const FLEET_IGNORED: readonly ["state/", "worktrees/", "projects/"];
+/**
+ * Well-known state file names. The lease lock is built by M1-P3 and the
+ * watcher beacon by M1-P5 (convention FM-043); doctor reads both as files
+ * only, never probing a process (plan constraint C-2). Task currency, when
+ * a later phase needs it, comes exclusively from tasks/<id>/meta.json and
+ * the turn-end file, never from a log tail (plan constraint C-1).
+ */
+export declare const LOCK_FILE: string;
+export declare const BEACON_FILE: string;
+/** Typed accessors over a validated fleet home. */
+export interface Fleet {
+    root: string;
+    charterDir: string;
+    decisionsDir: string;
+    stateDir: string;
+    tasksDir: string;
+    worktreesDir: string;
+    projectsDir: string;
+    backlogPath: string;
+    packageJsonPath: string;
+    gitignorePath: string;
+    lockPath: string;
+    beaconPath: string;
+}
+/**
+ * Return the layout entries missing from dir, in declaration order.
+ * Directories are reported with a trailing slash. An empty result means
+ * the layout is complete.
+ */
+export declare function missingLayoutEntries(dir: string): string[];
+/**
+ * Validate the layout at dir and return typed accessors. Throws an Error
+ * naming every missing entry when the layout is incomplete.
+ */
+export declare function loadFleet(dir: string): Fleet;

package/dist/src/fleet.js

@@ -0,0 +1,80 @@
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+/**
+ * Fleet-home layout (kernel plan v1, M1-P2 step 1; blueprint section 3 with
+ * the SC-002/SC-003 resolutions). The fleet home is a small git repository:
+ * durable content (charter/, decisions/, tasks/, backlog.md, package.json,
+ * .gitignore) is tracked; state/, worktrees/, and projects/ are ephemeral
+ * and gitignored (plan decision D-4, PR-004).
+ */
+export const FLEET_DIRS = [
+    "charter",
+    "decisions",
+    "state",
+    "tasks",
+    "worktrees",
+    "projects",
+];
+/** Files every fleet home carries at its root. */
+export const FLEET_FILES = ["backlog.md", "package.json", ".gitignore"];
+/**
+ * Exactly these entries are gitignored: clones under projects/ are
+ * recoverable from their remotes, worktrees/ are disposable, state/ holds
+ * beacons and locks (SC-002, plan decision D-4, PR-004). Nothing else.
+ */
+export const FLEET_IGNORED = ["state/", "worktrees/", "projects/"];
+/**
+ * Well-known state file names. The lease lock is built by M1-P3 and the
+ * watcher beacon by M1-P5 (convention FM-043); doctor reads both as files
+ * only, never probing a process (plan constraint C-2). Task currency, when
+ * a later phase needs it, comes exclusively from tasks/<id>/meta.json and
+ * the turn-end file, never from a log tail (plan constraint C-1).
+ */
+export const LOCK_FILE = join("state", "orchestrator.lock");
+export const BEACON_FILE = join("state", "watcher.beacon");
+/**
+ * Return the layout entries missing from dir, in declaration order.
+ * Directories are reported with a trailing slash. An empty result means
+ * the layout is complete.
+ */
+export function missingLayoutEntries(dir) {
+    const missing = [];
+    for (const name of FLEET_DIRS) {
+        const p = join(dir, name);
+        if (!existsSync(p) || !statSync(p).isDirectory()) {
+            missing.push(`${name}/`);
+        }
+    }
+    for (const name of FLEET_FILES) {
+        const p = join(dir, name);
+        if (!existsSync(p) || !statSync(p).isFile()) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+/**
+ * Validate the layout at dir and return typed accessors. Throws an Error
+ * naming every missing entry when the layout is incomplete.
+ */
+export function loadFleet(dir) {
+    const root = resolve(dir);
+    const missing = missingLayoutEntries(root);
+    if (missing.length > 0) {
+        throw new Error(`not a fleet home: ${root} is missing ${missing.join(", ")}`);
+    }
+    return {
+        root,
+        charterDir: join(root, "charter"),
+        decisionsDir: join(root, "decisions"),
+        stateDir: join(root, "state"),
+        tasksDir: join(root, "tasks"),
+        worktreesDir: join(root, "worktrees"),
+        projectsDir: join(root, "projects"),
+        backlogPath: join(root, "backlog.md"),
+        packageJsonPath: join(root, "package.json"),
+        gitignorePath: join(root, ".gitignore"),
+        lockPath: join(root, LOCK_FILE),
+        beaconPath: join(root, BEACON_FILE),
+    };
+}

package/dist/src/gates/adapters/http-json.d.ts

@@ -0,0 +1,5 @@
+/** RFC 6901 JSON pointer resolution. Absent is distinguished from null. */
+export declare function resolvePointer(document: unknown, pointer: string): {
+    found: boolean;
+    value?: unknown;
+};