orchestrator-workflow 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { runInit } from "./init.js";
 export type { InitOptions } from "./init.js";
 export { runUninstall } from "./uninstall.js";
 export type { UninstallReport } from "./uninstall.js";
-export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
+export { detectHarnesses, parseHarnessList, parseHarnessOption, HARNESSES, } from "./detect.js";
 export type { Harness } from "./detect.js";
 export { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, MODEL_ALIASES, MODEL_CLASSES, PROFILES, ROLES, ROLE_TIERS, TIER_DEFS, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
 export type { ModelAlias, ModelClass, Profile, Role, Tier } from "./models.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { runInit } from "./init.js";
 export { runUninstall } from "./uninstall.js";
-export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
+export { detectHarnesses, parseHarnessList, parseHarnessOption, HARNESSES, } from "./detect.js";
 export { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, MODEL_ALIASES, MODEL_CLASSES, PROFILES, ROLES, ROLE_TIERS, TIER_DEFS, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
 export { PACKAGE_VERSION } from "./assets.js";

package/dist/init.d.ts

@@ -36,7 +36,17 @@ export interface InitOptions {
      * by the role's own preselected model.
      */
     opencodeClassModels?: Record<ModelClass, string | undefined>;
+    /**
+     * Repo kit-version pin (distinct from the actually-installed `version`),
+     * so a later `apply` command can gate on it. A `string` sets a new
+     * recorded kit-version pin; `null` clears an existing pin; `undefined`
+     * (the default, omitted) carries the previous manifest's pin forward
+     * unchanged. An empty or whitespace-only string is normalized to a clear
+     * too, the same as `null`.
+     */
+    pin?: string | null;
 }
+export declare const MANIFEST_PATH: string;
 export interface Manifest {
     kit: string;
     version: string;
@@ -52,6 +62,31 @@ export interface Manifest {
      */
     files: Record<string, string>;
     installedAt: string;
+    /**
+     * Optional kit-version pin recorded for this repo (distinct from
+     * `version`, the actually-installed kit version). Absent when no pin was
+     * ever recorded or an existing one was cleared.
+     */
+    pin?: string;
+    /**
+     * True only when the raw manifest JSON's `harnesses` field was itself an
+     * array AND that raw array had zero elements -- i.e. the operator
+     * recorded an explicit empty harness set (a real `--harness none`
+     * install). An array with entries that all fail the known-harness filter
+     * (e.g. `["cursor"]`, or `["Claude"]` with the wrong case) also filters
+     * down to `harnesses: []` but must NOT set this flag: the raw field was
+     * never actually recorded as empty, it just failed to name anything this
+     * kit recognizes, and treating that the same as a deliberate `none` would
+     * silently degrade a live install to templates-only on a plain re-run
+     * (see CHANGELOG). A missing/malformed `harnesses` field (not an array at
+     * all) is the same "not a recorded empty set" case and also leaves this
+     * `false`. Only `readInstalledManifest` ever sets this from an actual
+     * on-disk manifest. A synthetic previous
+     * (e.g. `apply`'s `buildApplyPrevious` in cli.ts) leaves it `undefined`,
+     * which the harnesses-stickiness gate in `cli-inputs.ts` treats as "not
+     * recorded" and therefore never sticky.
+     */
+    harnessesRecordedEmpty?: boolean;
 }
 /**
  * A manifest can be hand-written or tampered with, and uninstall deletes by

package/dist/init.js

@@ -6,7 +6,7 @@ import { HARNESSES } from "./detect.js";
 import { CLASS_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, READ_ONLY_ROLES, ROLES, ROLE_TIERS, TIER_DEFS, assertValidModelId, claudeModelValue, isProfile, opencodeModelValue, rolesForProfile, } from "./models.js";
 import { emptyReport, ensureClaudeImport, installFile, upsertMarkerSection, } from "./writers.js";
 const SKILL_NAME = "orchestrator-workflow";
-const MANIFEST_PATH = join(".ai", "workflow", "manifest.json");
+export const MANIFEST_PATH = join(".ai", "workflow", "manifest.json"); // shared with doctor.ts/cli.ts (L9); see readInstalledManifest below
 function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
@@ -44,7 +44,17 @@ export function readInstalledManifest(targetDir) {
     const candidate = raw;
     if (candidate.kit !== SKILL_NAME)
         return undefined;
-    const harnesses = (Array.isArray(candidate.harnesses) ? candidate.harnesses : []).filter((value) => HARNESSES.includes(value));
+    // Captured before filtering, and deliberately on the RAW array's own
+    // length, not the filtered one: an invalid array element (a string, an
+    // unknown harness name) also filters down to `harnesses: []` below, but
+    // must not be mistaken for a deliberate recorded `harnesses: []` -- see
+    // the `Manifest.harnessesRecordedEmpty` doc comment above for why.
+    const rawHarnessesIsArray = Array.isArray(candidate.harnesses);
+    const rawHarnesses = rawHarnessesIsArray
+        ? candidate.harnesses
+        : [];
+    const harnessesRecordedEmpty = rawHarnessesIsArray && rawHarnesses.length === 0;
+    const harnesses = rawHarnesses.filter((value) => HARNESSES.includes(value));
     const models = {};
     if (typeof candidate.models === "object" && candidate.models !== null) {
         for (const role of ROLES) {
@@ -81,15 +91,28 @@ export function readInstalledManifest(targetDir) {
     // (the same per-field-degradation style as `profile` above) rather than
     // throwing on a legacy manifest.
     const tiers = typeof candidate.tiers === "boolean" ? candidate.tiers : false;
+    // A hand-written or damaged manifest may carry a non-string `pin`; that
+    // degrades to "no recorded pin" here (the same per-field-degradation
+    // style as `profile`/`tiers` above) rather than throwing. An empty or
+    // whitespace-only stored `pin` degrades the same way: it can never
+    // usefully name a kit version to gate on, so it is dropped rather than
+    // carried forward as a value nothing can act on.
     return {
         kit: SKILL_NAME,
         version: typeof candidate.version === "string" ? candidate.version : "",
         harnesses,
+        harnessesRecordedEmpty,
         models: models,
         profile,
         tiers,
         files,
         installedAt: typeof candidate.installedAt === "string" ? candidate.installedAt : "",
+        // The kit-version pin is deliberately free-form here: unlike the
+        // fields above it never reaches generated frontmatter, a shell, or a
+        // path, and the command that gates on it validates the value itself.
+        ...(typeof candidate.pin === "string" && candidate.pin.trim() !== ""
+            ? { pin: candidate.pin.trim() }
+            : {}),
     };
 }
 function yamlQuote(value) {
@@ -265,6 +288,18 @@ export function runInit(options) {
     const tiers = options.tiers ?? false;
     const report = emptyReport();
     const previous = readInstalledManifest(targetDir);
+    // `null` clears an existing pin, a string sets a new one, and omitted
+    // (`undefined`) carries the previous manifest's pin forward unchanged. An
+    // empty or whitespace-only string is normalized to a clear as well: it can
+    // never usefully name a kit version to gate on, so treating it as a
+    // sticky value would let a stray empty input linger unnoticed instead of
+    // clearing the pin the caller most likely meant.
+    const normalizedPin = typeof options.pin === "string"
+        ? options.pin.trim() === ""
+            ? null
+            : options.pin.trim()
+        : options.pin;
+    const pin = normalizedPin === null ? undefined : (normalizedPin ?? previous?.pin);
     const installedFiles = {};
     // Both leftover-note loops below are ledger-driven, not enumeration-
     // driven: they only ever push a note for a relative path that the
@@ -331,6 +366,64 @@ export function runInit(options) {
             }
         }
     }
+    // Dropping a harness this run (a previously installed harness no longer
+    // in options.harnesses -- including the whole set collapsing to
+    // `--harness none`) leaves that harness's files on disk but out of the
+    // manifest's file ledger, the same untracked-leftover shape as the two
+    // note loops above; surface it the same way instead of a silent leftover
+    // for `uninstall` to trip over later. Unlike the two loops above (which
+    // only ever touch claude/opencode agent files), this one also covers
+    // codex's SKILL.md under `.agents/`, since codex has no per-role agent
+    // files but its skill file is still a ledger-tracked kit-owned file.
+    //
+    // Deliberately keyed off `HARNESSES` (every known harness) and
+    // `previous.files` (the raw file ledger) rather than `previous.harnesses`
+    // (the sanitized, filtered harness list): a damaged/hand-edited manifest
+    // whose raw `harnesses` field lists a valid harness under an unrecognized
+    // name (e.g. `["cursor"]` where it once said `["claude"]`) filters that
+    // harness's name out of `previous.harnesses` entirely, but its files are
+    // still sitting in `previous.files` under `.claude/`; deriving the
+    // dropped-harness set from `previous.harnesses` would silently miss those
+    // notes (see CHANGELOG). Checking each
+    // known harness's own file-ledger prefix directly is immune to that: a
+    // harness with no files in the ledger under its prefix produces no notes
+    // either way, whether or not `previous.harnesses` ever named it.
+    if (previous) {
+        const harnessDirs = {
+            claude: ".claude",
+            codex: ".agents",
+            opencode: ".opencode",
+        };
+        for (const harness of HARNESSES) {
+            if (options.harnesses.includes(harness))
+                continue;
+            const prefix = harnessDirs[harness] + sep;
+            for (const relativePath of Object.keys(previous.files)) {
+                if (relativePath.startsWith(prefix)) {
+                    report.notes.push(`${relativePath}: now untracked after --harness dropped ${harness}; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                }
+            }
+        }
+        // AGENTS.md/CLAUDE.md are never ledger-tracked in the first place
+        // (upsertMarkerSection/ensureClaudeImport below write them directly,
+        // not through installKitFile, so they never enter previous.files);
+        // when the harness set collapses to none this run, this install skips
+        // writing them (see the `options.harnesses.length > 0` guard below),
+        // so note them by on-disk existence instead of a ledger lookup -- the
+        // same untracked signal for a file the ledger never recorded. Gated on
+        // ledger evidence (any known harness's file prefix present in
+        // `previous.files`), not on the sanitized `previous.harnesses`, for the
+        // same reason as the loop above: a damaged manifest can filter a valid
+        // harness out of `previous.harnesses` while its files remain recorded.
+        const hadTrackedHarnessFiles = Object.keys(previous.files).some((relativePath) => HARNESSES.some((harness) => relativePath.startsWith(harnessDirs[harness] + sep)));
+        if (hadTrackedHarnessFiles && options.harnesses.length === 0) {
+            for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+                if (existsSync(join(targetDir, name))) {
+                    report.notes.push(`${name}: now untracked after --harness dropped to none; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                }
+            }
+        }
+    }
     /**
      * Installs a kit-owned file. An unedited file (it still matches the hash
      * recorded at install time) is updated in place when the kit content
@@ -360,10 +453,15 @@ export function runInit(options) {
     }
     installKitFile(join(".ai", "runs", ".gitkeep"), "");
     // Codex and opencode read AGENTS.md natively; Claude Code gets it via the
-    // CLAUDE.md import. The policy section is therefore installed regardless of
-    // the harness selection. AGENTS.md and CLAUDE.md are user-owned: only the
-    // fenced section and the import line are ever touched.
-    upsertMarkerSection(report, join(targetDir, "AGENTS.md"), readAsset("agents-md-section.md"));
+    // CLAUDE.md import. The policy section is therefore installed whenever any
+    // harness is selected, regardless of which one. AGENTS.md and CLAUDE.md
+    // are user-owned: only the fenced section and the import line are ever
+    // touched. `options.harnesses.length === 0` is templates-only mode
+    // (`--harness none`): only `.ai/workflow/**` and `.ai/runs/.gitkeep` are
+    // written, so AGENTS.md is left untouched (and never created) too.
+    if (options.harnesses.length > 0) {
+        upsertMarkerSection(report, join(targetDir, "AGENTS.md"), readAsset("agents-md-section.md"));
+    }
     const skill = readAsset(join("skill", "SKILL.md"));
     if (options.harnesses.includes("claude")) {
         installKitFile(join(".claude", "skills", SKILL_NAME, "SKILL.md"), skill);
@@ -427,6 +525,7 @@ export function runInit(options) {
         profile,
         tiers,
         files: installedFiles,
+        ...(pin !== undefined ? { pin } : {}),
     };
     const manifestPath = join(targetDir, MANIFEST_PATH);
     if (previous &&
@@ -438,6 +537,7 @@ export function runInit(options) {
             profile: previous.profile,
             tiers: previous.tiers,
             files: previous.files,
+            ...(previous.pin !== undefined ? { pin: previous.pin } : {}),
         }) === JSON.stringify(desired)) {
         report.skipped.push(manifestPath);
     }

package/dist/operator-manifest.d.ts

@@ -0,0 +1,277 @@
+import type { Harness } from "./detect.js";
+import type { Profile, Role } from "./models.js";
+export declare const OPERATOR_HOME_DIRNAME = ".orchestrator-workflow";
+export declare const OPERATOR_HOME_ENV = "ORCHESTRATOR_WORKFLOW_HOME";
+export declare const OPERATOR_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Operator-level defaults applied when a target is (re-)applied without its
+ * own explicit flags. `models` is a `Partial<Record<Role, string>>` rather
+ * than a full `Record`, mirroring `readInstalledManifest`'s per-role
+ * degradation: a hand-written or legacy operator manifest may carry only
+ * some roles, and the rest should fall back to `DEFAULT_MODELS` at the call
+ * site rather than forcing every role to be present here.
+ */
+export interface OperatorManifestDefaults {
+    harnesses: Harness[];
+    profile: Profile;
+    tiers: boolean;
+    models: Partial<Record<Role, string>>;
+}
+/** One target directory this operator has applied the kit to. */
+export interface OperatorTarget {
+    path: string;
+    lastAppliedVersion: string;
+    lastAppliedAt: string;
+}
+export interface OperatorManifest {
+    kit: "orchestrator-workflow";
+    schemaVersion: 1;
+    defaults: OperatorManifestDefaults;
+    targets: OperatorTarget[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Resolves the operator-level home directory. Precedence: an explicit
+ * argument, then `ORCHESTRATOR_WORKFLOW_HOME`, then `~/.orchestrator-workflow/`.
+ * Both the explicit argument and the env var are made absolute via
+ * `node:path`'s `resolve` (relative to `process.cwd()`), matching the
+ * Precedence: an explicit argument, then the environment override, then the
+ * default directory under the user's home.
+ * access, no directory creation, no env-var reads beyond the lookup itself.
+ */
+export declare function resolveOperatorHome(explicit?: string): string;
+/** Creates a fresh operator manifest with no targets yet applied. */
+export declare function createOperatorManifest(defaults: OperatorManifestDefaults, now?: string): OperatorManifest;
+/**
+ * Reads the operator-level manifest at `<home>/manifest.json`, if any. The
+ * file can be hand-written or damaged, so every field is sanitized the same
+ * way `readInstalledManifest` sanitizes a per-repo manifest: anything
+ * invalid degrades to a safe default instead of throwing. Only the
+ * envelope fields (`kit`, `schemaVersion`) are hard requirements; a
+ * mismatch there means "not a manifest we recognize" and the whole read
+ * returns `undefined` rather than guessing.
+ */
+export declare function readOperatorManifest(home: string): OperatorManifest | undefined;
+/** Default lock-acquire timeout, in milliseconds. Deliberately kept above
+ * {@link DEFAULT_LOCK_STALE_MS}: a caller that starts anywhere from 0ms up
+ * to `DEFAULT_LOCK_STALE_MS` after a killed holder left its lock behind
+ * must still live long enough, polling, to see that lock cross the
+ * staleness threshold and reclaim it, rather than timing out first. */
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 40000;
+/** Default age, in milliseconds, past which a held lock directory is
+ * treated as abandoned and reclaimed. See {@link DEFAULT_LOCK_TIMEOUT_MS}
+ * for why this must stay smaller than the timeout. */
+export declare const DEFAULT_LOCK_STALE_MS = 30000;
+/** Default delay, in milliseconds, between acquire retries. */
+export declare const DEFAULT_LOCK_POLL_MS = 20;
+/** Options accepted by {@link withOperatorManifestLock}, exposed only so
+ * tests can shrink the timeout/staleness/poll windows below their
+ * production defaults; callers outside test code should omit this
+ * entirely. */
+export interface OperatorManifestLockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    pollMs?: number;
+}
+/** Thrown by {@link withOperatorManifestLock} when the lock could not be
+ * acquired within `timeoutMs`. Callers distinguish this from any error
+ * `fn` itself might throw so they can print lock-specific operator
+ * guidance instead of a generic failure. */
+export declare class OperatorManifestLockTimeoutError extends Error {
+    constructor(lockPath: string);
+}
+/**
+ * Decides, from a lock directory's age measured *after* it was renamed
+ * aside during a reclaim attempt, whether that renamed copy should be
+ * destroyed (a genuinely abandoned lock) or handed back to its real owner
+ * (a lock that turned out fresh once re-checked; see
+ * {@link withOperatorManifestLock}'s reclaim comment for why this second
+ * check exists at all). `postAgeMs` is `undefined` when the renamed copy
+ * could no longer be stat'd by the time this runs (already gone, e.g. a
+ * third acquisition raced in and took it over): that is treated as
+ * hand-back-safe, not stale-and-destroy, since a lock this call cannot
+ * age must not be destroyed on its behalf — the same "when in doubt,
+ * don't tear down what might still be someone else's critical section"
+ * stance {@link withOperatorManifestLock}'s doc comment describes for its
+ * own `finally` release guard. A pure function so both branches, and the
+ * `undefined` case, are unit-testable without spawning a lock directory.
+ */
+export declare function shouldDestroyReclaimedLock(postAgeMs: number | undefined, staleMs: number): boolean;
+/**
+ * Runs `fn` while holding an advisory, same-machine lock on the operator
+ * manifest at `<home>/manifest.json`, so a read-modify-write sequence
+ * (read the manifest, compute an updated copy, write it back) that this
+ * function wraps end to end cannot interleave with another process's own
+ * read-modify-write against the same `home`. {@link updateOperatorManifest}
+ * is the only call site that should ever use this directly; it is what
+ * makes the locked read-modify-write the sole write path to the manifest.
+ *
+ * Mechanics: `mkdirSync(<home>/.manifest.lock)` is used as the mutex,
+ * since directory creation is atomic on every filesystem Node targets
+ * (POSIX `mkdir(2)`, Windows `CreateDirectory`): a second, concurrent
+ * `mkdirSync` call for the same path fails with `EEXIST` rather than
+ * silently succeeding, exactly the primitive a mutual-exclusion lock
+ * needs. Right after `mkdirSync` succeeds, a fresh random token is written
+ * to `<lockPath>/owner`: this is the lock's owner identity, and it is what
+ * makes both the stale-lock reclaim below and the release in `finally`
+ * safe under contention (see each for why).
+ *
+ * A caller that finds the lock held retries with a short synchronous sleep
+ * (`sleepSync`, `Atomics.wait` on a throwaway `SharedArrayBuffer`, not a
+ * CPU-spinning busy loop) until either it acquires the lock or `timeoutMs`
+ * (default {@link DEFAULT_LOCK_TIMEOUT_MS}) elapses, in which case it
+ * throws {@link OperatorManifestLockTimeoutError} without ever calling
+ * `fn`. On every failed attempt (not just the first), a lock directory
+ * older than `staleMs` (default {@link DEFAULT_LOCK_STALE_MS}, checked via
+ * its mtime) is treated as abandoned, most likely left behind by a process
+ * that crashed or was killed between acquiring and releasing it, and
+ * reclaim is attempted: `renameSync(lockPath, <lockPath>.<token>.stale)`
+ * moves it out of the way, then the renamed copy is removed. `renameSync`
+ * on a POSIX filesystem is atomic, so of any two waiters racing to reclaim
+ * the same stale-looking directory, at most one rename can ever succeed;
+ * the loser's `renameSync` throws (the source is already gone) and it
+ * falls through to the normal retry/timeout handling instead of also
+ * entering the critical section. Re-checking staleness on every attempt
+ * (rather than once per call) is safe precisely because of that atomicity:
+ * repeating the check cannot itself cause two callers to both believe they
+ * reclaimed the same lock, it only means a caller that starts partway
+ * through another's abandoned-lock window still gets a chance to reclaim
+ * it once that window is crossed, instead of being stuck waiting out the
+ * full timeout.
+ *
+ * The staleness check and the rename are still two separate syscalls, not
+ * one atomic operation, so a second process could complete an entire fresh
+ * acquisition of its own in the gap between them; the winning `renameSync`
+ * would then have relocated that fresh, actively-held lock rather than the
+ * abandoned one the check inspected. This is closed by re-checking age a
+ * second time on the renamed copy, which only the caller that just renamed
+ * it can observe (so this second read is itself race-free): a lock that
+ * was genuinely fresh still reads as fresh there, and is handed back
+ * (renamed to `lockPath` again) rather than destroyed, so its real owner
+ * is undisturbed (short of the exceedingly narrow case where a third
+ * acquisition lands in that same brief hand-back gap, at which point there
+ * is nothing left to hand it back to; that owner's own eventual release
+ * still no-ops safely, see `finally` below).
+ *
+ * This lock is advisory (nothing stops a caller from touching the
+ * manifest file without going through it, exactly like a POSIX file
+ * lock) and same-machine only (a directory on a network filesystem
+ * shared across hosts is not a safe mutex primitive here); it protects
+ * cooperating `orchestrator-workflow` processes on one machine against
+ * each other, not against an uncooperative writer or a multi-host setup.
+ * `home` is created first (`mkdirSync(home, { recursive: true })`) since
+ * the lock directory lives inside it and a first-ever `apply`/`setup`
+ * against a brand-new operator home would otherwise have nowhere to put
+ * it. The lock is released in `finally`, including when `fn` throws, but
+ * only if the owner file inside it still holds this call's own token: if
+ * another process's stale-lock reclaim has since taken the directory over
+ * (the true holder ran long enough past `staleMs` for a waiter to evict
+ * it), this call's own token no longer matches what is in the owner file,
+ * and removing the directory here would tear down a lock that is no
+ * longer this call's to release, leaving the new owner's critical section
+ * unprotected mid-flight. Skipping the removal in that case is the
+ * correct, if imperfect, response: the directory is left for its actual
+ * current owner to release normally.
+ */
+export declare function withOperatorManifestLock<T>(home: string, fn: () => T, options?: OperatorManifestLockOptions): T;
+/** The three states an operator-manifest read can land in: no file at
+ * `<home>/manifest.json` at all (`absent`, the fresh-operator case); a file
+ * that exists but `readOperatorManifest` could not turn into a manifest
+ * (`unreadable`, e.g. corrupt JSON, an unrecognized envelope, or a read
+ * failure such as a permissions error); or a file that parsed and
+ * validated (`ok`, with `manifest` set). Kept distinct from plain
+ * `readOperatorManifest`'s `OperatorManifest | undefined` so a caller (this
+ * module's own callers today, `apply`'s CLI action; `doctor`, once it
+ * exists, tomorrow) can tell "nothing set up yet" apart from "something is
+ * there and broken", since the two call for different operator advice: the
+ * former says run `setup`, the latter says back up and repair (or remove)
+ * the file first, since blindly running `setup` again would silently wipe
+ * whatever registry data survives in the damaged file.
+ */
+export type OperatorManifestState = {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+} | {
+    kind: "ok";
+    manifest: OperatorManifest;
+};
+export declare function operatorManifestState(home: string): OperatorManifestState;
+/**
+ * The single locked read-modify-write entry point for the operator
+ * manifest: every write to `<home>/manifest.json` (`setup`, `apply`,
+ * `doctor --prune`, and `adopt`'s own registration step in cli.ts, all four
+ * today) goes through this function rather than ever calling the lock or
+ * the raw writer directly, so no command can bypass the lock and race
+ * another's read-modify-write.
+ *
+ * The whole re-read, `mutate`, and write run inside one
+ * `withOperatorManifestLock` critical section: `mutate` is handed the
+ * manifest re-read *inside the lock* (`current`, `undefined` when
+ * `state.kind` is not `"ok"`) rather than whatever the caller may have read
+ * before calling this, since that earlier read can already be stale by the
+ * time the lock is granted (another locked writer's own read-modify-write
+ * could have landed in between). `state` is the full {@link
+ * OperatorManifestState} the re-read produced, handed to `mutate` alongside
+ * `current` so it can distinguish "no manifest yet" from "manifest present
+ * but unreadable" when that distinction changes what it should do.
+ *
+ * `mutate` returning `undefined` means "do not write anything": the
+ * manifest is left exactly as re-read, and the returned `written` is
+ * `false`. Returning an `OperatorManifest` writes it (via the internal,
+ * unlocked writer, safe here since the write happens inside the lock) and
+ * `written` is `true`; the written manifest is also returned as
+ * `manifest` for a caller that wants it without a further read. A write
+ * that refreshes an already-existing manifest (`current` truthy) is also
+ * stamped with a fresh `updatedAt` here, unless `mutate`'s own returned
+ * value already carries a distinct one of its own, in which case that
+ * value is written verbatim (see the write itself, below, for the exact
+ * condition).
+ */
+export declare function updateOperatorManifest(home: string, mutate: (current: OperatorManifest | undefined, state: OperatorManifestState) => OperatorManifest | undefined, options?: OperatorManifestLockOptions): {
+    state: OperatorManifestState;
+    written: boolean;
+    manifest?: OperatorManifest;
+};
+/**
+ * The operator-facing message for `apply`'s locked registration step
+ * finding the operator manifest not `"ok"` (unreadable or gone) once the
+ * lock was granted. The two cases get distinct wording: an unreadable
+ * manifest says the kit install itself already succeeded and only the
+ * registry write failed (unlike the *pre-install* unreadable check, which
+ * runs before any install work and so must not claim one happened), while
+ * a manifest gone missing mid-lock keeps its own separately-worded advice.
+ * A pure, exported function (rather than inlined at its one call site in
+ * cli.ts) so the wording can be unit-tested without spawning the CLI.
+ */
+export declare function applyRegistrationFailureMessage(manifestKind: "unreadable" | "absent", manifestPath: string, targetDir: string): string;
+/**
+ * Realpath that never throws: a recorded target whose directory has since
+ * been removed or moved (the `missing` case a later doctor reports) must not
+ * make an unrelated upsert fail, so the stored path is compared as written
+ * when it can no longer be resolved. Exported so cli.ts resolves a target
+ * path the same guarded way this module does internally, rather than
+ * keeping its own duplicate copy of the same guard.
+ */
+export declare function safeRealpath(candidate: string): string;
+/**
+ * Returns a new manifest with `targetPath` recorded as applied, plus
+ * whether `targetPath` was already registered (an update) rather than
+ * newly added, so a caller does not need its own separate, and
+ * potentially inconsistent, check against the same targets array. Pure:
+ * does not mutate `manifest` or its nested `targets` array/entries.
+ * Targets are deduplicated by realpath (`safeRealpath`, guarded against a
+ * target directory that no longer exists) rather than raw string
+ * equality, so the same directory reached via a symlink or a differently
+ * cased/relative path still updates the existing entry in place instead of
+ * appending a duplicate; the update branch also rewrites the stored
+ * `path` to the resolved realpath, so an entry once written as a raw,
+ * non-realpath string (a hand-edited manifest, or one written before this
+ * normalization existed) is normalized going forward instead of needing
+ * `safeRealpath` on every future comparison against it.
+ */
+export declare function upsertOperatorTarget(manifest: OperatorManifest, targetPath: string, appliedVersion: string, appliedAt: string): {
+    manifest: OperatorManifest;
+    alreadyRegistered: boolean;
+};