@skanl/brambo-environment 0.1.1

package/dist/doctor.js

@@ -0,0 +1,551 @@
+import { access, constants, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { BRAMBO_ERROR_CODES, REGISTRY_ENTRY_TYPES } from '@skanl/brambo-contracts';
+import { noExecutorsDetected, projectCommandFor, runScope, scopeDirectory } from './init.js';
+/**
+ * What `brambo init` WOULD do about each kind — and only ever what brambo can
+ * itself perform. A `Record` over the closed kind union, so a kind added without
+ * an answer here does not compile: "each finding carries what brambo would do
+ * about it" is a type error away from being false, rather than a promise.
+ */
+export const RESOLUTION = {
+    edited: "brambo never overwrites an entry that changed since it wrote it; projecting again leaves your edit exactly as it is",
+    'removed-by-user': 'brambo never re-adds an entry you deleted; projecting again leaves it absent',
+    'foreign-collision': 'brambo never resolves a collision with content its ledger does not claim; projecting again leaves it untouched',
+    'not-initialised': "`brambo init` (or `brambo project init`) creates brambo's state here; doctor creates nothing",
+    'no-executor': 'brambo projects into configurations that already exist and creates none, so `brambo init` would write nothing here and exits 2',
+    'registry-unreadable': 'brambo never replaces a registry document it cannot read; `brambo init` fails on it and projects nothing, so no entry is deleted from any vendor file',
+    'registry-version-ahead': 'the document is not damaged: this build is simply older than the one that wrote it, and brambo refuses a format it does not speak rather than reading half of it. `brambo init` fails on it and projects nothing, so no entry is deleted from any vendor file and not one byte of the document is changed',
+    'retired-type': 'brambo reads and lists the entry but hands it to no target, so projecting again neither writes nor removes anything for it; brambo never deletes a registry entry by itself, because removing one is a decision and a decision is yours',
+    'ledger-damaged': 'brambo leaves the ledger exactly as it is and claims nothing it cannot read; until it is readable again brambo reports its own entries as foreign and touches none of them',
+    'projection-warning': 'brambo surfaced this from the projection run and resolves none of it by itself; `brambo init` runs through the same condition',
+    'out-of-date': 'projecting makes this location match the registry — for a skills root that can mean REMOVING a tree brambo wrote, not only writing one. Brambo checked the location is writable, which is weaker than a guarantee: an ACL, a mount option or another process holding it can still refuse the write, and on Windows that check sees only the read-only attribute',
+    'not-writable': 'brambo cannot write here, so projecting fails on this location and changes nothing rather than half-applying it',
+    unprojectable: 'no target can express this entry, so projecting again changes nothing for it; it stays out of this configuration',
+    'legacy-block': "`brambo remediate discard --executor <id>` removes exactly this block and leaves every other byte of the file alone; projecting again neither reads nor removes it. Where the detail says brambo will NOT take it, that is the reason, and brambo leaves the file untouched",
+    'target-failed': 'projecting again fails the same way for this executor and leaves its file untouched; the other executors are unaffected',
+    'worktree-leftover': 'projecting neither reads nor touches a worktree, so `brambo init` would do nothing about this; brambo never sweeps a leftover on its own, because removing a checkout on a run nobody asked to be destructive is exactly what a startup sweep would be',
+};
+/**
+ * The exit for every state brambo reports — TOTAL over {@link DiagnosisFindingKind},
+ * so a finding kind added without one does not compile.
+ *
+ * IT LIVES IN DOCTOR, beside the kinds, and not beside `remediate` — because the
+ * first version put it beside the capability, nothing outside the tests consumed
+ * it, and `brambo doctor` went on printing *"brambo never overwrites an entry that
+ * changed since it wrote it; projecting again leaves your edit exactly as it is"*
+ * for four of the five states this story gave an exit to. The trap was closed in
+ * the code and left open on the only surface a user reads. Every `resolution`
+ * below is now composed from this record, so the product cannot know an exit the
+ * report does not print.
+ */
+export const FINDING_EXITS = {
+    edited: {
+        by: 'remediation',
+        remediations: ['adopt', 'release'],
+        detail: "`adopt` takes ownership of what is there now, after which `brambo init` replaces it with the registry's version — that is how you get brambo's version back, and it is a REPLACEMENT of your edit. `release` drops the claim and leaves your edit alone permanently",
+    },
+    'removed-by-user': {
+        by: 'remediation',
+        remediations: ['release'],
+        detail: '`release` drops the claim, which makes the location free again, so the next `brambo init` writes the entry back. To keep it absent instead, the entry has to leave the registry, which is `brambo remove <type> <id>` (`brambo project remove <type> <id>` for a project-scope entry)',
+    },
+    'foreign-collision': {
+        by: 'remediation',
+        remediations: ['adopt', 'release'],
+        detail: "`adopt` takes ownership of what occupies brambo's location, exactly as it is now — including brambo's OWN tree left unclaimed by a crash, and a tree that is only PARTLY there, which it claims as the subset that exists. It claims what is THERE and nothing else, so where the location holds nothing brambo can identify there is nothing to claim and `adopt` refuses rather than writing an empty claim. `release` is the exit where the collision comes from a claim brambo holds and cannot use. Where the detail says the VENDOR's document is ambiguous — a location declared twice, a container brambo cannot address — neither verb applies until that is fixed in the file itself, and brambo's own ledger is not involved",
+    },
+    'ledger-damaged': {
+        by: 'remediation',
+        remediations: ['repair'],
+        detail: "`repair` rewrites brambo's own ledger to hold exactly the records it can read. It describes what it will drop before it drops it, and it touches no vendor file",
+    },
+    'legacy-block': {
+        by: 'remediation',
+        remediations: ['discard'],
+        detail: "`discard` removes exactly the block a previous brambo build wrote and nothing else. Where the detail says brambo will NOT take it — markers it cannot bound, a key it cannot attribute — that is the reason, brambo leaves the file untouched, and the block has to be removed by hand",
+    },
+    'not-initialised': {
+        by: 'command',
+        command: 'brambo init',
+        // ONLY WHAT THE OTHER HALF DID NOT SAY. `RESOLUTION['not-initialised']`
+        // already names the command and says doctor creates nothing; this said the
+        // same sentence again, and the user read both in one line.
+        detail: "it writes brambo's own state directory and registry document, and nothing into any executor's configuration",
+    },
+    'out-of-date': {
+        by: 'command',
+        command: 'brambo init',
+        // THE SAME RULE `not-initialised` CARRIES ABOVE, applied to the sibling that
+        // missed it: only what the other half did not say. This used to end "that is
+        // `brambo init`", which the caller's scope override cannot reach — the
+        // override rewrites the "To leave this state" half and the detail is
+        // concatenated raw. Driven at project scope, one resolution said BOTH
+        // `brambo project init` and `brambo init`, and a user reading the tail runs
+        // the machine command for a project finding.
+        //
+        // It names no command now, because the half in front of it already prints
+        // the right one. What it adds instead is the thing `RESOLUTION` does not
+        // say: that this verdict cost the user nothing.
+        detail: 'doctor reached it by running the same merge projecting would and writing none of it, so the location is exactly as you left it',
+    },
+    'no-executor': {
+        by: 'outside-brambo',
+        // The premise -- that brambo projects into configurations and creates none --
+        // belongs to `RESOLUTION` and was restated here for eleven words. This half
+        // carries the ACTION, which is the only part the other one cannot give.
+        detail: 'Run one of them at least once so a configuration exists to project into; nothing in brambo has to be fixed first',
+    },
+    'registry-unreadable': {
+        by: 'outside-brambo',
+        // The refusal and its reason are `RESOLUTION`'s sentence; repeating them
+        // here cost eight words before the part a user acts on.
+        detail: "Repair or remove that document. Brambo's ownership ledger is a different file and is not involved, so nothing it already claims is at risk while you do",
+    },
+    // The ONE action, and it is the opposite of the sibling's above. The premise —
+    // the document is intact and brambo refuses it whole — is `RESOLUTION`'s
+    // sentence; this half carries only what the user does about it, which is the
+    // part that other one cannot give.
+    'registry-version-ahead': {
+        by: 'outside-brambo',
+        detail: 'Install a brambo at least as new as the build that wrote it; the detail above names both versions. The document itself needs nothing done to it, and deleting it or editing it back into a shape this older build accepts is how the entries in it get lost',
+    },
+    'not-writable': {
+        by: 'outside-brambo',
+        detail: 'brambo cannot grant itself permission; the location has to become writable',
+    },
+    // A COMMAND, and it has to be: retiring a word from the registry vocabulary
+    // while the entries written under it stay unreadable-or-unremovable is the
+    // dead end M4.C exists to abolish, reached this time by upgrading. `brambo
+    // remove` therefore accepts a retired type even though `brambo add` refuses
+    // one, and the finding's own detail names the exact spelling for this entry.
+    'retired-type': {
+        by: 'command',
+        command: 'brambo remove <type> <id>',
+        detail: 'the entry is not damaged and the document is not corrupt — brambo simply no longer declares that word. `brambo remove` still accepts a retired type even though `brambo add` refuses one, which is how an entry written by an older build leaves without hand-editing the document',
+    },
+    // Reclassified OUT of `outside-brambo` by story M4.D, which is the SAFE
+    // direction: the M4.C ledger flagged reclassification INTO `outside-brambo` as
+    // the move that weakens the totality proof, because it lets a hard state be
+    // answered with a plausible sentence. This goes the other way — the sentence
+    // is replaced by a command the binary dispatches.
+    unprojectable: {
+        by: 'command',
+        command: 'brambo remove <type> <id>',
+        detail: 'this is informational and is never counted as a problem, so nothing has to be done about it. Nothing makes the entry PROJECTABLE — no target can express it — and what `brambo remove <type> <id>` changes is that it stops being reported, because the entry has left the registry. Use `brambo project remove <type> <id>` for an entry registered at a project scope',
+    },
+    'target-failed': {
+        by: 'outside-brambo',
+        detail: 'the coded error on the finding names the cause; brambo leaves this executor untouched until it is addressed, and the others are unaffected',
+    },
+    'projection-warning': {
+        by: 'outside-brambo',
+        detail: 'a condition the projection run surfaced with no more specific reading than its own code; brambo resolves none of it by itself',
+    },
+    // A COMMAND, and the same shape `retired-type` reached: the state is fully
+    // resolvable and the thing that resolves it is a verb the binary dispatches.
+    // Naming the removal here is also what keeps the report and the capability one
+    // answer -- the verb re-runs the identical removal the interrupted one was
+    // performing, so a leftover cannot be resolved by a second code path that
+    // reasons differently from the first.
+    'worktree-leftover': {
+        by: 'command',
+        command: 'brambo workspace remove <id>',
+        detail: 'the removal is finished by running it again: the same checks, the same refusals, and the same retirement the interrupted one was performing. It removes only what brambo holds a record for, and it still refuses a tree with modified or untracked files or one whose commit no ref contains -- resuming an interrupted removal is not a licence to skip the checks. Run it with no id to resolve every leftover in the project at once',
+    },
+};
+/** Every kind this remediation is the named exit for. Derived, never listed. */
+export function findingKindsFor(remediation) {
+    return Object.keys(FINDING_EXITS).filter((kind) => {
+        const exit = FINDING_EXITS[kind];
+        return exit.by === 'remediation' && exit.remediations.includes(remediation);
+    });
+}
+/**
+ * The exit, as the sentence a user reads. Composed from {@link FINDING_EXITS} so
+ * the command the product prints and the command the capability accepts are one
+ * string, and a remediation renamed upstream renames itself here.
+ */
+function exitSentence(kind, 
+/**
+ * WHICH STATE THE EXIT HAS TO LEAVE. `FINDING_EXITS` is a
+ * `Record<DiagnosisFindingKind, FindingExit>` with ONE command per kind and no
+ * scope axis, so every exit was rendered in the machine grammar. Driven at
+ * project scope: `brambo project doctor` reported an `edited` finding and named
+ * `brambo remediate adopt`, which exits 1 with
+ * `BRAMBO_PROJECTION_REMEDIATION_REFUSED` — brambo never remediates a state it
+ * did not just report, and the machine scope reported none. The command that
+ * works was never printed.
+ *
+ * The verb is spelled twice rather than interpolated, because that is what
+ * makes the printed-command invariant see a real verb in each — the same shape
+ * `retired-type` arrived at 300 lines below, after it printed
+ * `brambo project remove` for a global entry.
+ */
+scope, command) {
+    const exit = FINDING_EXITS[kind];
+    if (exit.by === 'remediation') {
+        return `To LEAVE this state, name it: ${exit.remediations
+            .map((remediation) => scope === 'machine' ? `\`brambo remediate ${remediation}\`` : `\`brambo project remediate ${remediation}\``)
+            .join(' or ')}. ${exit.detail}`;
+    }
+    // `command` is the SPELLING for this one finding, where the caller holds the
+    // concrete values. `FINDING_EXITS` can only declare the shape of the exit --
+    // `brambo remove <type> <id>` -- and printing a placeholder at a finding that
+    // already knows the type and the id makes the user translate a command brambo
+    // could have written out. `unprojectable` still prints the template, because
+    // its rows carry an entry id and no type; `retired-type` carries both.
+    if (exit.by === 'command')
+        return `To leave this state: \`${command ?? exit.command}\`. ${exit.detail}`;
+    return `Brambo cannot leave this state itself. ${exit.detail}`;
+}
+/**
+ * Which findings the exit code answers for. Total over the same union, for the
+ * same reason: a new kind has to be classified deliberately, not inherit
+ * "problem" from a default nobody chose.
+ */
+const SEVERITY = {
+    edited: 'problem',
+    'removed-by-user': 'problem',
+    'foreign-collision': 'problem',
+    'not-initialised': 'problem',
+    'no-executor': 'problem',
+    'registry-unreadable': 'problem',
+    // A PROBLEM, and the `unprojectable` test is what earns it: the light CAN be
+    // got back to green, by installing the build the document was already written
+    // for. It also names a condition OF THIS MACHINE — an older brambo in front of
+    // a newer document — rather than a standing architectural fact, so it fires on
+    // approximately no runs instead of on every one (spec M4.A's test, passed).
+    'registry-version-ahead': 'problem',
+    // A PROBLEM rather than info, and the exit code is again the reason. The test
+    // is whether a user can get the light back to green: `unprojectable` is info
+    // because no target can express the entry and deleting one the user
+    // deliberately registered is not a fix. Here one command clears it
+    // for good, and the entry is one no current build can create — leaving it
+    // silent would hide the single visible consequence of an upgrade.
+    'retired-type': 'problem',
+    'ledger-damaged': 'problem',
+    'projection-warning': 'problem',
+    'out-of-date': 'problem',
+    'not-writable': 'problem',
+    // The one INFO kind, and the exit code is the whole reason: no target can
+    // express the entry — a `skill` reaching a config target, a `skill` at project
+    // scope, an `mcp-server` with no command — so the only way exit 1 here could
+    // be got back to 0 is DELETING an entry the user deliberately registered,
+    // which is not a fix. Reported in full, never counted as diagnosed. (Story
+    // M4.D gave the kind a real exit, `brambo remove`; that changes how it is LEFT,
+    // not whether having it is wrong.)
+    unprojectable: 'info',
+    'target-failed': 'problem',
+    // A PROBLEM, and the Codex case is why: a `# BEGIN brambo-managed` block puts
+    // foreign sub-keys inside `[tools]` and `[skills]`, so a documented
+    // `--strict-config` run fails to load the user's ENTIRE config.toml. It is
+    // also fully resolvable, which is what earns a non-zero exit — the exit code
+    // is a promise that the light can be got back to green.
+    'legacy-block': 'problem',
+    // A PROBLEM: a half-removed worktree is a real state of brambo's own store,
+    // and one command clears it for good. The `unprojectable` test applies and
+    // passes — the light CAN be got back to green — so silence here would hide
+    // the one visible consequence of a run that was killed.
+    'worktree-leftover': 'problem',
+};
+/**
+ * Every kind, derived from a record TypeScript proves total. Exported for the
+ * tests that partition the kinds by what a finding of that kind must name — a
+ * hand-written list there would fall behind the union silently.
+ */
+export const DIAGNOSIS_FINDING_KINDS = Object.keys(RESOLUTION);
+/**
+ * How a projection warning is read. Keyed on the warning's own CODE rather than
+ * assumed: the engine seeds warnings from the ledger today, and a second source
+ * added upstream would otherwise ship silently wearing the ledger's resolution
+ * text. An unmapped code says exactly that instead.
+ */
+const WARNING_KIND = {
+    [BRAMBO_ERROR_CODES.projectionLedgerUnavailable]: 'ledger-damaged',
+};
+/**
+ * How a failed registry read is read, keyed on the store's own CODE — never on
+ * its message text (AD-7). Every code the store can raise that is NOT listed
+ * here is a document brambo could not read, which is what the fallback says.
+ */
+const REGISTRY_ERROR_KIND = {
+    [BRAMBO_ERROR_CODES.registryStoreVersionMismatch]: 'registry-version-ahead',
+};
+/** True when at least one finding is something wrong — the non-zero condition. */
+export function hasProblem(diagnosis) {
+    return diagnosis.findings.some((found) => found.severity === 'problem');
+}
+/**
+ * `finding`, bound to the scope being diagnosed.
+ *
+ * A CLOSURE rather than a parameter on all fourteen call sites, and that is the
+ * point: every one of them is inside `findingsFor`, which holds
+ * `diagnosis.scope`, so binding it once makes a scope-blind exit impossible to
+ * write here rather than possible-but-discouraged.
+ */
+function findingIn(scope) {
+    return (kind, detail, about = {}, command) => buildFinding(scope, kind, detail, about, command);
+}
+function buildFinding(scope, kind, detail, about = {}, 
+/** The concrete spelling of a `by: 'command'` exit; see {@link exitSentence}. */
+command) {
+    // Two halves, always: what PROJECTING again would do (which for five kinds is
+    // "nothing, forever"), and how to LEAVE the state. Shipping only the first is
+    // what made this command tell users four remediable states were terminal.
+    return {
+        kind,
+        severity: SEVERITY[kind],
+        ...about,
+        detail,
+        resolution: `${RESOLUTION[kind]} — ${exitSentence(kind, scope, command)}`,
+    };
+}
+async function isFile(path) {
+    return await stat(path).then((stats) => stats.isFile(), () => false);
+}
+/**
+ * Whether `access(W_OK)` is granted at `path` or, when nothing is there yet, at
+ * its nearest EXISTING ancestor — three-valued, because "brambo could not
+ * determine" must not be reported as "brambo cannot write".
+ */
+async function permitsWrite(path) {
+    let candidate = path;
+    for (;;) {
+        try {
+            await access(candidate, constants.W_OK);
+            return true;
+        }
+        catch (error) {
+            const code = error?.code;
+            // EPERM is the Windows spelling for a read-only file; EACCES the POSIX one.
+            if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS')
+                return false;
+            if (code !== 'ENOENT')
+                return undefined;
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return undefined;
+            candidate = parent;
+        }
+    }
+}
+/**
+ * Whether brambo could write at `path` — modelling the write brambo ACTUALLY
+ * performs, which is not `open(path, 'w')`. Every byte brambo lands goes through
+ * one atomic writer: a temp file created in the target's own directory, then
+ * renamed over the target.
+ *
+ * So the permission that decides the outcome is the DIRECTORY's, on both
+ * platforms — the temp file has to be created there, and rename() consults the
+ * containing directory, never the mode of the name it replaces. A 0444 target
+ * whose directory is writable is replaced without complaint on POSIX. Windows
+ * is the exception, and only Windows: rename over a file carrying the read-only
+ * attribute fails EPERM there, so that one check is guarded by the platform
+ * rather than applied to both. Both halves measured by execution (see the
+ * differential rows in `test/doctor.test.ts`).
+ *
+ * ponytail: `access(W_OK)` is advisory, not a guarantee — on Windows it sees the
+ * read-only attribute and not ACLs, and nothing survives another process taking
+ * the directory between the check and the write. That is why a positive answer
+ * only lets the `out-of-date` resolution say brambo CHECKED, never that it will
+ * succeed. Upgrade path: none worth having; a trial write is exactly the thing
+ * this command may not do.
+ *
+ * ponytail: a SYMLINKED target is probed at the link's own directory, not at the
+ * directory of the file `realpath` resolves to, which is where the writer lands
+ * it. Ceiling accepted deliberately: `realpath` is not one of the four fs verbs
+ * this package is allowed to import (`test/guard.test.ts`), and the answer is
+ * advisory either way. Upgrade path: the engine reports the resolved write
+ * target alongside the row, and this probes that.
+ */
+async function writableLocation(path) {
+    if (process.platform === 'win32' && (await isFile(path))) {
+        const target = await permitsWrite(path);
+        if (target !== true)
+            return target;
+    }
+    return await permitsWrite(dirname(path));
+}
+/**
+ * Everything wrong with one scope, in the order a reader needs it: brambo's own
+ * state first (a machine with nothing initialised explains every other row),
+ * then per target in catalogue order.
+ */
+async function findingsFor(diagnosis, registryError, retired, worktreeLeftovers) {
+    // Bound once, so no exit below can be rendered in the wrong grammar.
+    const finding = findingIn(diagnosis.scope);
+    const findings = [];
+    if (registryError !== undefined) {
+        findings.push(finding(REGISTRY_ERROR_KIND[registryError.code] ?? 'registry-unreadable', `${registryError.code}: ${registryError.message}`, { filePath: diagnosis.registryPath }));
+    }
+    else if (!(await isFile(diagnosis.registryPath))) {
+        // The REGISTRY DOCUMENT is the initialised signal, not brambo's directory:
+        // the ledger creates `<home>/.brambo` on its own first write, so one
+        // `brambo project init` anywhere would otherwise make the machine scope read
+        // as initialised forever — on the ordinary path, not an exotic one.
+        findings.push(finding('not-initialised', `brambo has no registry document at '${diagnosis.registryPath}'`, { filePath: diagnosis.registryPath }, 
+        // The override this parameter was built for. `FINDING_EXITS` holds
+        // `brambo init`, and at project scope that command exits 0 and leaves the
+        // project uninitialised — driven, then asserted by running what doctor
+        // printed and asking doctor again.
+        projectCommandFor(diagnosis.scope)));
+    }
+    for (const row of retired) {
+        // Both halves come from the ROW, never from the scope being diagnosed: the
+        // verb is the grammar that reaches the document the entry is actually in,
+        // and `filePath` is that document. `brambo project doctor` reads the global
+        // registry too, so deriving either from `diagnosis.scope` printed
+        // `brambo project remove <id>` for a global entry -- a command that exits 1,
+        // against a project document that does not hold it. The two spellings are
+        // separate literals so the printed-command invariant sees a real verb in
+        // each, and the concrete command goes to the EXIT sentence rather than into
+        // this detail, so the rendered line states the fact once and the command once.
+        const { entry } = row;
+        const removeCommand = row.scope === 'global'
+            ? `brambo remove ${entry.type} ${entry.id}`
+            : `brambo project remove ${entry.type} ${entry.id}`;
+        findings.push(finding('retired-type', `'${entry.id}' is a '${entry.type}' entry in the ${row.scope} registry, and '${entry.type}' is a type brambo no longer declares (it has ${REGISTRY_ENTRY_TYPES.join(', ')}); no target will ever take it`, { filePath: row.registryPath, entryId: entry.id }, removeCommand));
+    }
+    for (const leftover of worktreeLeftovers) {
+        // The command is SPELLED OUT with this leftover's own id rather than left as
+        // the `<id>` template the exit declares, for the reason `retired-type`'s
+        // block gives: a finding that already knows the id makes the user translate
+        // a command brambo could have written out.
+        findings.push(finding('worktree-leftover', leftover.detail, { filePath: leftover.path }, `brambo workspace remove ${leftover.id}`));
+    }
+    if (noExecutorsDetected(diagnosis)) {
+        // `brambo init` exits 2 on exactly this state, so a doctor that called it
+        // clean would certify an environment the very next command refuses.
+        findings.push(finding('no-executor', `no configuration was found for any executor brambo knows (${diagnosis.detected.map((detection) => detection.executorId).join(', ')})`));
+    }
+    for (const block of diagnosis.legacy) {
+        findings.push(finding('legacy-block', block.detail, {
+            executorId: block.executorId,
+            filePath: block.filePath,
+        }));
+    }
+    for (const warning of diagnosis.warnings) {
+        findings.push(finding(WARNING_KIND[warning.code] ?? 'projection-warning', `${warning.code}: ${warning.detail}`, {
+            ...(WARNING_KIND[warning.code] === 'ledger-damaged' ? { filePath: diagnosis.ledgerPath } : {}),
+        }));
+    }
+    // Brambo's own ledger is written for EVERY target a run produces a result for,
+    // changed or not, so an unwritable ledger fails a run that would otherwise be
+    // a no-op — and inspection cannot discover that by failing, because the write
+    // it would fail on is the one this mode skips.
+    if (diagnosis.targets.length + diagnosis.skills.length > 0 &&
+        (await writableLocation(diagnosis.ledgerPath)) === false) {
+        findings.push(finding('not-writable', `brambo's own ownership ledger '${diagnosis.ledgerPath}' is not writable, which fails every target of a run, not only the ones that would change`, { filePath: diagnosis.ledgerPath }));
+    }
+    // Config files first, then skills roots — the same catalogue order both
+    // arrays already carry, so one executor's two surfaces read together.
+    for (const target of [...diagnosis.targets, ...diagnosis.skills]) {
+        const tree = diagnosis.skills.includes(target);
+        const at = { executorId: target.executorId, filePath: target.filePath };
+        if (target.error !== undefined) {
+            findings.push(finding('target-failed', `${target.error.code}: ${target.error.message}`, at));
+        }
+        if (target.wouldWrite) {
+            // Reported as one or the other, never both: `out-of-date` promises a write
+            // brambo would perform, and at a location brambo cannot write that promise
+            // is false forever — which is the one thing this command may not say.
+            //
+            // A skills ROOT is probed as itself rather than through its parent: the
+            // writer creates the root when it is absent, so the nearest existing
+            // ancestor is what decides, and `permitsWrite` walks up to find it. A
+            // config file is probed through its DIRECTORY, because that is where the
+            // temp-file-then-rename actually lands.
+            const writable = tree ? await permitsWrite(target.filePath) : await writableLocation(target.filePath);
+            // ABSENT IS NOT DIFFERENT, and saying so is AD-5 applied to this command's
+            // own sentence. Driven before this: a project that had never been
+            // projected reported "the bytes in '<path>' differ from what projecting
+            // would produce" — a byte comparison brambo did not perform, about a file
+            // with no bytes — and the CONTROL, a file that really was there and really
+            // differed, produced a byte-identical sentence. Two states, one report,
+            // and the one brambo invented is the commoner of the two.
+            //
+            // `ProjectionResult` carries `written`/`byteDelta` and no presence, and
+            // threading one through would change a published contract for a sentence.
+            // A `stat` here instead: this branch already probes the filesystem for
+            // writability, so the answer costs one more syscall on a path it is
+            // holding anyway.
+            const present = await stat(target.filePath).then(() => true, () => false);
+            findings.push(writable === false
+                ? finding('not-writable', `brambo would rewrite '${target.filePath}' and the location is not writable`, at)
+                : finding('out-of-date', present
+                    ? tree
+                        ? `the skills brambo materialises under '${target.filePath}' differ from what projecting would produce`
+                        : `the bytes in '${target.filePath}' differ from what projecting would produce`
+                    : tree
+                        ? `'${target.filePath}' does not exist yet, so nothing of what projecting would materialise is there`
+                        : `'${target.filePath}' does not exist yet, so nothing of what projecting would write is there`, at, 
+                // Same override, same reason as `not-initialised`: this exit is
+                // "project again", and at project scope `brambo init` is not that.
+                projectCommandFor(diagnosis.scope)));
+        }
+        for (const entry of target.drift) {
+            findings.push(finding(entry.kind, entry.detail, { ...at, location: entry.location, entryId: entry.entryId }));
+        }
+        for (const entry of target.unprojectable) {
+            findings.push(finding('unprojectable', entry.reason, { ...at, entryId: entry.entryId }));
+        }
+    }
+    return findings;
+}
+function toDiagnosisTarget(row) {
+    return {
+        executorId: row.executorId,
+        targetId: row.targetId,
+        filePath: row.filePath,
+        wouldWrite: row.changed,
+        drift: row.drift,
+        unprojectable: row.unprojectable,
+        ...(row.error === undefined ? {} : { error: row.error }),
+    };
+}
+/**
+ * Diagnoses one scope and writes nothing at all.
+ *
+ * A clean environment yields no findings; anything wrong yields at least one
+ * with `severity: 'problem'`, which is what lets a script branch on it.
+ * Reporting stops at the scope the caller named: doctor never goes looking for
+ * other projects brambo has bound.
+ */
+export async function diagnose(options = {}) {
+    // Every field read ONCE, here, before the first await — the same TOCTOU rule
+    // `initMachine` follows, and it bites harder here: an accessor that answered
+    // with a temp directory now and the real home directory later would have the
+    // real one diagnosed under a promise that nothing would be touched.
+    const { homeDir = homedir(), projectDir, scope = 'machine', worktreeLeftovers = [] } = options;
+    const home = await scopeDirectory('the home directory', homeDir);
+    // Resolved and validated only when it is the scope being diagnosed. `brambo
+    // doctor` must not fail on a working directory it was never asked about — and
+    // `process.cwd()` THROWS when the process's directory has been deleted, which
+    // is exactly the kind of machine this command gets run on.
+    const root = scope === 'machine'
+        ? home
+        : await scopeDirectory('the project directory', projectDir ?? process.cwd());
+    // No log sink: nothing is invoked, so nothing is recorded as invoked.
+    const report = await runScope(scope, home, root, undefined, 'inspect');
+    const body = {
+        scope,
+        bramboDir: report.bramboDir,
+        registryPath: report.registryPath,
+        ledgerPath: report.ledgerPath,
+        entryCount: report.entryCount,
+        detected: report.detected,
+        // Named field by field rather than spread, so this payload's key order is
+        // authored and pinned instead of inherited from a rest object.
+        targets: report.targets.map(toDiagnosisTarget),
+        skills: report.skills.map(toDiagnosisTarget),
+        legacy: report.legacy,
+        skipped: report.skipped,
+        warnings: report.warnings,
+    };
+    return {
+        ...body,
+        findings: await findingsFor(body, report.registryError, report.retired, worktreeLeftovers),
+    };
+}

package/dist/executors.d.ts

@@ -0,0 +1,88 @@
+import type { ProjectionConfigTarget, ProjectionMaterialiseTarget } from '@skanl/brambo-contracts';
+import type { FileFormat, NativeMcpRead } from '@skanl/brambo-projection';
+/**
+ * One filesystem location consulted for an executor, and what was found.
+ *
+ * `exists` is deliberately THREE-valued. Collapsing "brambo could not look" into
+ * "absent" makes the no-executor exit tell a user that nothing is installed
+ * when the truth is that a permission error, a dangling link or an ELOOP stopped
+ * the check — and it fails in the direction that hides a config brambo would
+ * otherwise have written to.
+ */
+export interface EvidencePath {
+    readonly path: string;
+    /** true present · false definitively absent · undefined could not determine. */
+    readonly exists: boolean | undefined;
+    /** errno behind an `undefined` verdict; absent otherwise. */
+    readonly error?: string;
+}
+export interface ExecutorDetection {
+    readonly executorId: string;
+    /** The projection target this executor is served by, present or not. */
+    readonly targetId: string;
+    /** True only where an evidence path was OBSERVED to exist. Nothing else sets it. */
+    readonly present: boolean;
+    readonly evidence: readonly EvidencePath[];
+}
+export interface ExecutorProfile {
+    readonly executorId: string;
+    readonly targetId: string;
+    /** Consulted in order; any hit makes the executor present. */
+    readonly evidencePaths: (homeDir: string) => readonly string[];
+    readonly machineConfig: (homeDir: string) => string;
+    /** Absent when the vendor has no verified project-scope configuration. */
+    readonly projectConfig: ((projectDir: string) => string) | undefined;
+    readonly createTarget: (filePath: string) => ProjectionConfigTarget;
+    /**
+     * The READ direction of the same file `createTarget` writes into (M11.A D2).
+     *
+     * A closure over this executor's own trait record, exactly like `createTarget`
+     * above, rather than the trait record itself: `brambo ingest` needs the entries
+     * a vendor's document declares and nothing else about the format, and the
+     * document's format, container key and entry shape all stay where D1 put them.
+     * `undefined` from it means the file is absent, which is not an error (AD-5).
+     */
+    readonly readMcpEntries: (filePath: string) => Promise<NativeMcpRead | undefined>;
+    /**
+     * The skills root brambo has VERIFIED this executor reads, or `undefined`.
+     *
+     * Undefined is the honest answer, not a gap: an executor whose skills
+     * location brambo has not proven by running the real binary reports its skills
+     * unprojectable, exactly as before this story. There is no project-scope
+     * entry here at all for the same reason — materialising into a project scope
+     * is Ask-First in this story's Boundaries, so `brambo project init` reports
+     * skills unprojectable rather than inventing a second location.
+     */
+    readonly machineSkills: ((homeDir: string) => string) | undefined;
+    readonly skillsTargetId: string | undefined;
+    readonly createSkillsTarget: ((rootPath: string) => ProjectionMaterialiseTarget) | undefined;
+    /**
+     * Where a PREVIOUS brambo build wrote brambo's own vocabulary, and in which
+     * format — correction-01 C6.
+     *
+     * These are not locations brambo writes; they are locations brambo has to be
+     * able to CLEAN. Stories 2.2 and 2.3 put a reserved `$.brambo` key into the
+     * JSON family and a `# BEGIN brambo-managed` block into Codex's TOML, none of
+     * which any executor reads and the Codex one of which stops the user's whole
+     * `config.toml` from loading under `--strict-config`. A machine that ran one
+     * of those builds still has the litter, and the corrected build cannot produce
+     * it — so it is reported and removed rather than merged around.
+     *
+     * MACHINE SCOPE ONLY, and that is a measurement rather than an omission: the
+     * builds that wrote these had no project scope at all (`brambo project init`
+     * arrives in Story 2.7a, after correction-01), so there is no project-scope
+     * location that can hold one.
+     */
+    readonly legacyConfig: ((homeDir: string) => {
+        filePath: string;
+        fileFormat: FileFormat;
+    }) | undefined;
+}
+export declare const EXECUTOR_PROFILES: readonly ExecutorProfile[];
+/**
+ * Every executor brambo knows about, whether it was found, and the exact paths
+ * consulted for each. Returns the FULL catalogue on purpose: a run that detects
+ * nothing has to be able to tell the user what was looked for and where, and a
+ * list that omitted the misses could not.
+ */
+export declare function detectExecutors(homeDir: string): Promise<ExecutorDetection[]>;