@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/adapters/load.js

@@ -0,0 +1,440 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readRegularFileIfPresent, singleLine } from "../task.js";
+/**
+ * ADAPTER SELECTION AND LOADING (kernel plan M4, M4-P4; M4-D-03 at
+ * delivery/plan/m4-intake.md:729).
+ *
+ * THE RESOLUTION ROOT IS THE WHOLE SECURITY PROPERTY, and it is the reason
+ * this module exists rather than a one-line `await import(specifier)` at the
+ * spawn call site. Loading an adapter executes third-party code INSIDE the
+ * orchestrator process, the same process that holds delegated merge
+ * authority under DR-0012. DR-0029 Part 2c's untrusted-project-content
+ * boundary does not exist and M4-D-23 recommends it is not built in M4, so
+ * the only mitigation available is WHERE the code is resolved from:
+ *
+ *   - the FLEET HOME is owner-controlled and already pins `@tiphys/kernel`
+ *     exactly, which is what makes it a boundary at all;
+ *   - the PROJECT CLONE is the thing under review and may contain anything
+ *     a contributor pushed, including a `node_modules/` directory.
+ *
+ * So resolution is rooted at `<fleet home>/package.json` rather than at this
+ * module or at `process.cwd()`. A plain `await import(specifier)` resolves
+ * relative to THIS MODULE's URL, which is the kernel checkout, and
+ * `import.meta.resolve(specifier, parent)` silently ignores its second
+ * argument unless Node is started with `--experimental-import-meta-resolve`
+ * (measured on v26.6.0, 2026-09-17: the parent was ignored and the specifier
+ * resolved from the CALLER's file). Both of those are the shape this module
+ * refuses to be.
+ *
+ * THE ROOTING IS NOT BY ITSELF THE PROPERTY, AND THE SENTENCE THAT STOOD HERE
+ * SAID IT WAS (CR-B-004, re-raised as CR-F-CRED-002 and CH-002).
+ *
+ * Until this round this paragraph asserted, without qualification, that
+ * "NOTHING here ever consults the project clone". That is true of BARE
+ * specifiers, which is the only shape M4-P4 criterion 2's witness exercises:
+ * `createRequire` walks the fleet home and its PARENTS looking for
+ * `node_modules`, and the project clone sits BELOW the fleet home at
+ * `<fleet>/projects/<name>`, so no such walk reaches it. It was FALSE of the
+ * module. Measured at `ad2428b`, with a module in the project clone that drops
+ * a sentinel on import: a bare specifier did not evaluate it, an ABSOLUTE
+ * specifier did, and the fleet-relative `./projects/demo/evil.mjs` did,
+ * because a relative path does not walk up looking for `node_modules`, it
+ * walks DOWN the tree the rooting chose.
+ *
+ * The mechanism is a constraint that holds for one INPUT SHAPE, documented as
+ * holding for the module. Both halves are now checked against the RESOLVED
+ * REAL PATH, which is the only thing that describes where the code actually
+ * comes from, rather than against the specifier's spelling:
+ *
+ *   - a resolved path inside `<fleet>/projects/` is refused WHATEVER the
+ *     specifier's shape, because the project tree is the thing under review;
+ *   - a PATH-SHAPED specifier (absolute, or beginning `./` or `../`) whose
+ *     resolved path is outside the fleet home is refused, because an absolute
+ *     specifier can point anywhere and a relative one can climb out with
+ *     `../`. A BARE specifier is exempt from the second check only, because
+ *     `createRequire`'s parent walk legitimately finds a hoisted
+ *     `node_modules` above the fleet home, and refusing that would break an
+ *     ordinary install rather than a hazard.
+ *
+ * `realpathSync` is used for both, so a symlink planted inside the fleet home
+ * pointing into the project clone is refused by the same check rather than by
+ * a second one.
+ *
+ * WHAT IS STILL NOT DEFENDED, said here so the next reader does not re-derive
+ * it: an operator who types an absolute path INTO the fleet home gets what
+ * they typed, and the fleet home is owner-controlled by assumption. This moves
+ * the boundary to the fleet home for every specifier shape; it does not defend
+ * inside it.
+ *
+ * WHAT THIS MODULE DOES NOT DEFEND. Once a specifier resolves inside the
+ * fleet home, its code runs. A legitimate fleet-home adapter that is later
+ * compromised is not covered by anything here, and no criterion of this
+ * phase claims otherwise: this phase MOVES the boundary to the fleet home,
+ * it does not defend inside it. That residue is M4-D-23's, stated rather
+ * than implied.
+ */
+/**
+ * The built-in adapter's name, and the one name a loaded adapter may not
+ * claim (M4-P4 criterion 5).
+ *
+ * IT LIVES HERE RATHER THAN IN `src/spawn.ts` so that the runtime import
+ * edge runs one way only: `src/spawn.ts` imports this value, and this module
+ * imports nothing but a TYPE back. A value-level cycle between the launch
+ * module and the loader would evaluate one of them inside the other's
+ * temporal dead zone the first time an import order changed, which is a
+ * failure nothing in the suite would predict.
+ *
+ * The launch record's `adapter` field (src/spawn.ts:113) is the only thing
+ * that ever says what ran. A loaded adapter naming itself after the built-in
+ * one makes every later record ambiguous, and the ambiguity is unresolvable
+ * after the fact because the record is the only witness. This is the
+ * misattribution guard src/gates/schemas/release-record.schema.json:26
+ * already instantiates for release records, applied one layer down.
+ */
+export const BUILT_IN_ADAPTER_NAME = "subprocess";
+/**
+ * The fleet-home `package.json` field that names a default adapter, as a
+ * JSON pointer written out in the one place that reads it.
+ *
+ * `tiphys.adapter` rather than a top-level key: the kernel's own
+ * `package.json` already namespaces its configuration under `tiphys`
+ * (package.json:52), so a fleet home carrying kernel configuration uses the
+ * same namespace rather than inventing a second convention.
+ */
+export const FLEET_ADAPTER_FIELD = "tiphys.adapter";
+/**
+ * The specifier the fleet home declares as its default, if any.
+ *
+ * READ THROUGH `readRegularFileIfPresent`, never `readFileSync`: the fleet
+ * home is a directory this process does not own the contents of, and a FIFO
+ * at `package.json` would hang the spawn rather than refuse it. That is the
+ * hazard CR-520 records for `meta.json`, one path along.
+ *
+ * A fleet home with no `package.json`, no `tiphys` object, or no `adapter`
+ * key declares NOTHING, which is a different fact from declaring something
+ * unusable: the first yields `undefined` and the built-in default, the
+ * second is a refusal naming the field.
+ */
+export function fleetAdapterSpecifier(fleet) {
+    const read = readRegularFileIfPresent(fleet.packageJsonPath);
+    if (read.kind === "absent") {
+        return { ok: true, specifier: undefined };
+    }
+    if (read.kind === "refused") {
+        return {
+            ok: false,
+            reason: `the fleet home package.json could not be read to find a default ` +
+                `adapter (${read.reason})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `the fleet home package.json ${fleet.packageJsonPath} does not parse as ` +
+                `JSON (${singleLine(error.message)}), so the ` +
+                `${FLEET_ADAPTER_FIELD} field cannot be read`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {
+            ok: false,
+            reason: `the fleet home package.json ${fleet.packageJsonPath} does not parse as ` +
+                `an object, so the ${FLEET_ADAPTER_FIELD} field cannot be read`,
+        };
+    }
+    const tiphys = parsed.tiphys;
+    if (tiphys === undefined) {
+        return { ok: true, specifier: undefined };
+    }
+    if (typeof tiphys !== "object" || tiphys === null || Array.isArray(tiphys)) {
+        return {
+            ok: false,
+            reason: `the fleet home package.json ${fleet.packageJsonPath} declares tiphys as ` +
+                `${Array.isArray(tiphys) ? "an array" : typeof tiphys}, and ` +
+                `${FLEET_ADAPTER_FIELD} can only be read from an object`,
+        };
+    }
+    const adapter = tiphys.adapter;
+    if (adapter === undefined) {
+        return { ok: true, specifier: undefined };
+    }
+    if (typeof adapter !== "string" || adapter.trim() === "") {
+        return {
+            ok: false,
+            reason: `the fleet home package.json ${fleet.packageJsonPath} declares ` +
+                `${FLEET_ADAPTER_FIELD} as ${typeof adapter === "string" ? "an empty string" : typeof adapter}, ` +
+                `and a default adapter must be a non-empty module specifier`,
+        };
+    }
+    return { ok: true, specifier: adapter };
+}
+/**
+ * Resolve `specifier` with Node module resolution ROOTED AT THE FLEET HOME,
+ * then evaluate it and check that what came back is an adapter.
+ *
+ * `createRequire(<fleet home>/package.json)` is the rooting. Every lookup it
+ * performs starts at the fleet home and walks its PARENTS, which is ordinary
+ * Node resolution with a base this process chose; the project clone lives
+ * BELOW the fleet home (`<fleet>/projects/<name>`), so no walk from the
+ * fleet home can ever reach its `node_modules`. A relative specifier
+ * (`./adapters/mine.js`) is likewise resolved against the fleet home rather
+ * than against the current working directory.
+ *
+ * THE RESOLVED PATH IS THEN CHECKED FOR CONTAINMENT (CR-F-CRED-002, CH-002).
+ * `requireFromFleet.resolve` is where the rooting happens and it is NOT where
+ * the boundary is enforced, because a path-shaped specifier is not subject to
+ * the walk the rooting performs. `refuseResolvedAdapterPath` below is the
+ * enforcement and it runs BEFORE the `import`, so a refused module is never
+ * evaluated; see the module comment for the two rules and for what they do
+ * not cover.
+ *
+ * THE CONDITION SET IS `require`, AND THAT IS A REAL LIMITATION RATHER THAN
+ * AN OVERSIGHT. `require.resolve` applies an `exports` map under the
+ * `require` condition, so a package whose map offers ONLY an `import`
+ * condition fails to resolve here with ERR_PACKAGE_PATH_NOT_EXPORTED
+ * (measured, node v26.6.0, 2026-09-17). Resolution succeeding says nothing
+ * about the module SYSTEM: the resolved path is then imported as an ES
+ * module through a file URL, so an ESM adapter loads correctly as long as its
+ * `exports` map offers a `require` or `default` condition, or a bare string.
+ * The refusal below says so, because an adapter author reading
+ * "cannot be resolved" with no further detail would go looking in the wrong
+ * place. The alternative, a parameterised ESM resolver, does not exist in
+ * stable Node; see the module docs above for the measurement.
+ */
+/**
+ * Is `specifier` a PATH rather than a package name? Node's own rule, and it is
+ * spelled out rather than approximated: a specifier is relative when it begins
+ * `./` or `../` (or their platform separator forms), and absolute when
+ * `isAbsolute` says so. Everything else is bare and reaches the `node_modules`
+ * walk.
+ */
+function isPathShapedSpecifier(specifier) {
+    if (isAbsolute(specifier)) {
+        return true;
+    }
+    for (const prefix of ["./", "../", `.${sep}`, `..${sep}`]) {
+        if (specifier.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolve a path to its real location, or return it unchanged when it cannot
+ * be resolved. An unresolvable path is NOT treated as safe: it is returned as
+ * it stands and the containment rules below judge it, so the failure mode of
+ * this helper is a refusal rather than a pass.
+ */
+function realPathOrItself(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** Whether `path` is `root` itself or sits underneath it. */
+function isInside(root, path) {
+    if (path === root) {
+        return true;
+    }
+    const rel = relative(root, path);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * THE CONTAINMENT RULES, applied to the RESOLVED REAL PATH (CR-F-CRED-002,
+ * CH-002). Exported so a test can drive both rules directly without staging a
+ * module on disk for every member; `loadAdapter` is the only caller in `src/`.
+ *
+ * Returns a refusal reason, or undefined to allow. Both rules name the
+ * resolved path, because an operator reading the refusal has to be able to see
+ * WHERE the specifier landed, which is precisely the thing the specifier's own
+ * spelling hides.
+ */
+export function refuseResolvedAdapterPath(fleet, specifier, origin, resolved) {
+    const realResolved = realPathOrItself(resolved);
+    const realFleetRoot = realPathOrItself(fleet.root);
+    const realProjectsDir = realPathOrItself(fleet.projectsDir === "" ? join(realFleetRoot, "projects") : fleet.projectsDir);
+    if (isInside(realProjectsDir, realResolved)) {
+        return (`the adapter ${specifier} (${origin}) resolves to ${realResolved}, which is ` +
+            `inside the project tree ${realProjectsDir}; a project clone is the code ` +
+            `under review and loading an adapter runs it inside the orchestrator ` +
+            `process, so no specifier of any shape may resolve there`);
+    }
+    if (isPathShapedSpecifier(specifier) && !isInside(realFleetRoot, realResolved)) {
+        return (`the adapter ${specifier} (${origin}) is a path-shaped specifier resolving ` +
+            `to ${realResolved}, which is outside the fleet home ${realFleetRoot}; the ` +
+            `fleet home is the only resolution root the kernel trusts for adapters, and ` +
+            `a path specifier is not constrained by the rooting the way a package name is`);
+    }
+    return undefined;
+}
+export async function loadAdapter(fleet, specifier, origin) {
+    const requireFromFleet = createRequire(fleet.packageJsonPath);
+    let resolved;
+    try {
+        resolved = requireFromFleet.resolve(specifier);
+    }
+    catch (error) {
+        const code = error.code ?? "";
+        return {
+            ok: false,
+            reason: `the adapter ${specifier} (${origin}) could not be resolved from the ` +
+                `fleet home ${fleet.root}, which is the ONLY resolution root the kernel ` +
+                `uses for adapters: install it in the fleet home, and note that an ` +
+                `exports map offering only an import condition does not resolve here ` +
+                `(${code === "" ? singleLine(String(error)) : code})`,
+        };
+    }
+    const containmentRefusal = refuseResolvedAdapterPath(fleet, specifier, origin, resolved);
+    if (containmentRefusal !== undefined) {
+        return { ok: false, reason: containmentRefusal };
+    }
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `the adapter ${specifier} (${origin}) resolved to ${resolved} but could ` +
+                `not be evaluated: ${singleLine(String(error))}`,
+        };
+    }
+    return checkAdapterShape(module, specifier, origin, resolved);
+}
+/**
+ * IS THIS AN ADAPTER (M4-P4 criterion 4)?
+ *
+ * The three shapes the criterion names are three ways a module can be
+ * IMPORTABLE and not be an adapter, and each of them is silent at the import
+ * itself: a module with no default export, a default export with no `launch`,
+ * and a `launch` that is not callable. Left unchecked, the first two surface
+ * as `TypeError: adapter.launch is not a function` thrown out of `spawnTask`
+ * AFTER pool create has made a worktree, a branch and a pool record, which is
+ * the same "refusal that arrives as a crash, after creation" shape M4-P3's
+ * requirement checks exist to prevent (src/spawn.ts's checkAdapterRequirements).
+ *
+ * A FOURTH CHECK IS HERE THAT THE CRITERION DOES NOT NAME, and it is declared
+ * rather than smuggled: the adapter's `name` must be a non-empty string.
+ * Criterion 5 refuses one particular name, and `undefined` written into the
+ * launch record's `adapter` field would defeat the whole point of that
+ * criterion by making the record say nothing at all. A guard on the value of
+ * a field that may be absent is a guard that cannot go red for the absent
+ * case.
+ *
+ * Every refusal names the SPECIFIER and the member, because an operator
+ * reading it has a module to go and fix and needs to know which one.
+ */
+export function checkAdapterShape(module, specifier, origin, resolved) {
+    const where = `the adapter ${specifier} (${origin}), resolved to ${resolved},`;
+    if (typeof module !== "object" || module === null) {
+        return { ok: false, reason: `${where} did not evaluate to a module object` };
+    }
+    if (!Object.hasOwn(module, "default")) {
+        return {
+            ok: false,
+            reason: `${where} has no default export; an adapter module exports its ` +
+                `ExecutorAdapter as the default export`,
+        };
+    }
+    const candidate = module.default;
+    if (typeof candidate !== "object" || candidate === null) {
+        return {
+            ok: false,
+            reason: `${where} exports a default that is ${candidate === null ? "null" : typeof candidate}, ` +
+                `not an object with a launch member`,
+        };
+    }
+    const launch = candidate.launch;
+    if (launch === undefined) {
+        return {
+            ok: false,
+            reason: `${where} exports a default with no launch member; ExecutorAdapter ` +
+                `requires launch(request)`,
+        };
+    }
+    if (typeof launch !== "function") {
+        return {
+            ok: false,
+            reason: `${where} exports a default whose launch member is ${typeof launch}, ` +
+                `not a function; ExecutorAdapter requires launch(request)`,
+        };
+    }
+    const name = candidate.name;
+    if (typeof name !== "string" || name.trim() === "") {
+        return {
+            ok: false,
+            reason: `${where} exports a default with no usable name member; the launch ` +
+                `record's adapter field is the only thing that says what ran, so an ` +
+                `adapter must name itself with a non-empty string`,
+        };
+    }
+    if (name === BUILT_IN_ADAPTER_NAME) {
+        return {
+            ok: false,
+            reason: `${where} names itself ${BUILT_IN_ADAPTER_NAME}, which is the built-in ` +
+                `adapter's name; a loaded adapter may not claim it, because the launch ` +
+                `record's adapter field would then no longer say which one ran`,
+        };
+    }
+    return { ok: true, adapter: candidate };
+}
+/**
+ * WHICH ADAPTER THIS SPAWN USES, AND WHY (M4-P4 criteria 1 and 6).
+ *
+ * WHICH SOURCE WINS, and it is explicit in the record rather than silent:
+ * the `--adapter` FLAG outranks the fleet-home default, and the fleet-home
+ * default outranks the built-in one.
+ *
+ * THE WORDING IS DELIBERATE AND IS NOT A STYLE CHOICE. The word this sentence
+ * would naturally use is claimed by four rows of
+ * delivery/plan/cutover/retirement-inventory.json, which assert that no kernel
+ * artifact states an authority order among charter, plan and decision records
+ * and enumerate BY NAME the `src/` files allowed to carry the token. A new
+ * file carrying it reddens `scripts/check-retirement-inventory.mjs`, correctly,
+ * because the checker cannot tell a benign use from a refuting one without a
+ * human reading it. This use is benign and incidental, so the token is not
+ * used here rather than the rows being widened from a phase that does not own
+ * that document. A flag is a per-spawn instruction and
+ * a fleet-home field is a standing one, so the narrower statement wins; the
+ * opposite order would make the flag unusable on any fleet that declared a
+ * default.
+ *
+ * `undefined` for the adapter means USE THE BUILT-IN ONE, and it is returned
+ * as `undefined` rather than as `subprocessAdapter` so that this module
+ * imports nothing but a type from `src/spawn.ts`. See BUILT_IN_ADAPTER_NAME
+ * above for why the import edge runs one way.
+ */
+export async function selectAdapter(fleet, flagSpecifier) {
+    if (flagSpecifier !== undefined) {
+        const origin = "--adapter";
+        const loaded = await loadAdapter(fleet, flagSpecifier, origin);
+        return loaded.ok ? { ok: true, adapter: loaded.adapter, origin } : loaded;
+    }
+    const declared = fleetAdapterSpecifier(fleet);
+    if (!declared.ok) {
+        return declared;
+    }
+    if (declared.specifier === undefined) {
+        return { ok: true, adapter: undefined, origin: "the built-in default" };
+    }
+    const origin = `the fleet home ${FLEET_ADAPTER_FIELD} field`;
+    const loaded = await loadAdapter(fleet, declared.specifier, origin);
+    return loaded.ok ? { ok: true, adapter: loaded.adapter, origin } : loaded;
+}

package/dist/src/brief.d.ts

@@ -0,0 +1,32 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Brief assembly (kernel plan v1, M1-P4 step 2; R-033b, R-083b).
+ *
+ * The brief for a task is written once, at spawn, to tasks/<id>/brief.md:
+ * the operator's brief file verbatim, followed by the fleet's
+ * environment-warnings file verbatim when the fleet has one. The
+ * warnings file is <fleet>/warnings.md (fleet root, tracked content, not
+ * the ignored state/ area). When no warnings file exists, brief.md is
+ * byte-identical to the brief file.
+ *
+ * Verbatim means verbatim: no heading, no banner, no rewriting. A brief
+ * is the durable instruction an implementer is judged against, and a
+ * kernel that edits it makes the audit trail lie. The only byte this
+ * module may add is a single newline between the two documents when the
+ * brief does not already end in one.
+ */
+/** The fleet's environment-warnings file, appended to every brief. */
+export declare const WARNINGS_FILE = "warnings.md";
+export declare function warningsPath(fleet: Fleet): string;
+export type BriefResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Assemble tasks/<id>/brief.md from briefFile. Returns the written path.
+ * The task directory must already exist.
+ */
+export declare function assembleBrief(fleet: Fleet, taskId: string, briefFile: string): BriefResult;

package/dist/src/brief.js

@@ -0,0 +1,66 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readRegularPathIfPresent, refuseOpenPathForWrite, } from "./fleet.js";
+import { briefPath } from "./task.js";
+/**
+ * Brief assembly (kernel plan v1, M1-P4 step 2; R-033b, R-083b).
+ *
+ * The brief for a task is written once, at spawn, to tasks/<id>/brief.md:
+ * the operator's brief file verbatim, followed by the fleet's
+ * environment-warnings file verbatim when the fleet has one. The
+ * warnings file is <fleet>/warnings.md (fleet root, tracked content, not
+ * the ignored state/ area). When no warnings file exists, brief.md is
+ * byte-identical to the brief file.
+ *
+ * Verbatim means verbatim: no heading, no banner, no rewriting. A brief
+ * is the durable instruction an implementer is judged against, and a
+ * kernel that edits it makes the audit trail lie. The only byte this
+ * module may add is a single newline between the two documents when the
+ * brief does not already end in one.
+ */
+/** The fleet's environment-warnings file, appended to every brief. */
+export const WARNINGS_FILE = "warnings.md";
+export function warningsPath(fleet) {
+    return join(fleet.root, WARNINGS_FILE);
+}
+/**
+ * Assemble tasks/<id>/brief.md from briefFile. Returns the written path.
+ * The task directory must already exist.
+ */
+export function assembleBrief(fleet, taskId, briefFile) {
+    /* THREE PATHS, NONE OF THEM THIS MODULE'S OWN, AND THE TYPE OF EACH IS
+       ESTABLISHED BEFORE IT IS OPENED (T-008's shape in shipped code). Until
+       this round all three were bare: `--brief` is named by the CALLER,
+       `warnings.md` is fleet content the kernel did not create, and the target
+       is a path this module CREATES, which is the write direction and blocks
+       on a FIFO exactly as a read does. A named pipe at any of them took
+       `tiphys spawn` down forever with zero output; `existsSync` did not help,
+       because a FIFO exists. */
+    const briefRead = readRegularPathIfPresent(briefFile);
+    if (briefRead.kind === "absent") {
+        return { ok: false, reason: `cannot read brief file ${briefFile}: it is absent` };
+    }
+    if (briefRead.kind === "refused") {
+        return { ok: false, reason: `cannot read brief file ${briefFile}: ${briefRead.reason}` };
+    }
+    let content = briefRead.body;
+    const warnings = warningsPath(fleet);
+    const warningsRead = readRegularPathIfPresent(warnings);
+    if (warningsRead.kind === "refused") {
+        return {
+            ok: false,
+            reason: `cannot read fleet warnings file ${warnings}: ${warningsRead.reason}`,
+        };
+    }
+    if (warningsRead.kind === "read") {
+        const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+        content = `${content}${separator}${warningsRead.body}`;
+    }
+    const target = briefPath(fleet, taskId);
+    const refusal = refuseOpenPathForWrite(target);
+    if (refusal !== undefined) {
+        return { ok: false, reason: `cannot write brief ${target}: ${refusal}` };
+    }
+    writeFileSync(target, content);
+    return { ok: true, value: target };
+}