@cotal-ai/cli 0.11.2 → 0.11.4

package/dist/lib/up-report.d.ts

@@ -0,0 +1,9 @@
+export interface DetachedStatus {
+    pid: number;
+    delivery: boolean;
+    authService: boolean;
+    manager: boolean;
+}
+/** Render only components confirmed running for this detached boot. */
+export declare function renderDetachedSummary(status: DetachedStatus): string;
+//# sourceMappingURL=up-report.d.ts.map

package/dist/lib/up-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"up-report.d.ts","sourceRoot":"","sources":["../../src/lib/up-report.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAMpE"}

package/dist/lib/up-report.js

@@ -0,0 +1,12 @@
+/** Render only components confirmed running for this detached boot. */
+export function renderDetachedSummary(status) {
+    const components = [`nats-server (pid ${status.pid})`];
+    if (status.delivery)
+        components.push("delivery daemon");
+    if (status.authService)
+        components.push("user-auth service");
+    if (status.manager)
+        components.push("manager");
+    return `✓ running in the background: ${components.join(", ")} - stop with: cotal down`;
+}
+//# sourceMappingURL=up-report.js.map

package/dist/lib/up-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"up-report.js","sourceRoot":"","sources":["../../src/lib/up-report.ts"],"names":[],"mappings":"AAOA,uEAAuE;AACvE,MAAM,UAAU,qBAAqB,CAAC,MAAsB;IAC1D,MAAM,UAAU,GAAG,CAAC,oBAAoB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,QAAQ;QAAE,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACxD,IAAI,MAAM,CAAC,WAAW;QAAE,UAAU,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,OAAO;QAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/C,OAAO,gCAAgC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,0BAA0B,CAAC;AACzF,CAAC"}

package/dist/seed/authority.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The three named seed-state files plus the durable authority backup, and the monotonic contract
+ * that keeps a deliberately-removed connector removed across a version bump.
+ *
+ * `ever-seeded` is the authority: the set of built-ins that were EVER seeded. It only grows. A name
+ * in it but absent from the extensions manifest was removed on purpose (leave it removed); a name
+ * NOT in it was never seeded (seed it). Losing this set would resurrect removals, so it is mirrored
+ * into an append-only backup — the only thing `--repair` can recover from. Write order per reconcile:
+ * authority (with its backup) first, then the witness, then the stamp LAST, so a stamp is never
+ * current ahead of the authority it certifies.
+ */
+export interface Authority {
+    /** Built-in connector names ever seeded on this machine. Monotonic — never shrinks. */
+    readonly everSeeded: string[];
+}
+export interface Witness {
+    readonly initialized: true;
+    /** The generation that first initialized this prefix (diagnostic; the stamp tracks the latest). */
+    readonly firstGeneration: string;
+}
+export interface Stamp {
+    /** The generation the last completed reconcile ran for. */
+    readonly generation: string;
+}
+export declare function readAuthority(): Authority | undefined;
+export declare function readAuthorityBackup(): Authority | undefined;
+export declare function readWitness(): Witness | undefined;
+export declare function readStamp(): Stamp | undefined;
+/** The ever-seeded set unioned with its monotonic backup. A live authority that lost ids (a truncated
+ *  or partially-corrupt write that still parsed) can only SHRINK the set; the backup is a superset, so
+ *  unioning it on read means a deliberately-removed connector is never resurrected by such a loss.
+ *  Returns undefined only when BOTH are absent (the genuinely-lost case the caller must fail loud on). */
+export declare function everSeededUnion(): Set<string> | undefined;
+/**
+ * Persist the ever-seeded authority. The backup is updated FIRST as a monotonic UNION (old backup ∪
+ * new set), so the recovery source is always a superset of the live authority and a crash between the
+ * two writes can only lose ids from the authority (which the backup then restores), never from both.
+ * An older binary that reads this must union unknown ids, never drop them.
+ */
+export declare function writeAuthority(everSeeded: Set<string>): void;
+/** Write the initialization witness once (idempotent; refreshing it would erase the first-seen gen). */
+export declare function ensureWitness(generation: string): void;
+/** Write the version stamp LAST — the only thing that flips the fast path to "reconcile complete". */
+export declare function writeStamp(generation: string): void;
+/** Recover a lost authority from the durable backup (for `--repair`). Undefined when even the backup
+ *  is gone — the caller REFUSES, because a witness alone cannot tell a removed connector from a
+ *  never-seeded future one. */
+export declare function recoverAuthorityFromBackup(): Set<string> | undefined;
+/** Move aside any seed-state file that no longer reads/validates, so a `--reset` can rebuild clean
+ *  state instead of wedging when a commit helper re-reads the same corrupt file. Returns the
+ *  quarantine paths (for reporting). `--reset` overwrites authority/backup/witness/stamp anyway; this
+ *  just guarantees the pre-write reads (e.g. {@link ensureWitness}) can't throw on a corrupt one. */
+export declare function quarantineCorruptSeedState(): string[];
+//# sourceMappingURL=authority.d.ts.map

package/dist/seed/authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../../src/seed/authority.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,SAAS;IACxB,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,mGAAmG;IACnG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,KAAK;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD,wBAAgB,aAAa,IAAI,SAAS,GAAG,SAAS,CAErD;AAED,wBAAgB,mBAAmB,IAAI,SAAS,GAAG,SAAS,CAE3D;AAED,wBAAgB,WAAW,IAAI,OAAO,GAAG,SAAS,CAEjD;AAED,wBAAgB,SAAS,IAAI,KAAK,GAAG,SAAS,CAE7C;AAED;;;0GAG0G;AAC1G,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAK5D;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;+BAE+B;AAC/B,wBAAgB,0BAA0B,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAGpE;AAED;;;qGAGqG;AACrG,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAmBrD"}

package/dist/seed/authority.js

@@ -0,0 +1,94 @@
+import { existsSync, renameSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { authorityBackupPath, authorityPath, readJsonFile, stampPath, witnessPath, writeJsonAtomic, } from "./paths.js";
+/** Every seed-state file is schema-validated on read: a syntactically-valid but wrong-shaped file is
+ *  as dangerous as corrupt JSON (a truncated authority would resurrect removed connectors), so it is
+ *  rejected the same way — loud, with the repair hint — never silently treated as a smaller set. */
+function validate(path, value, ok) {
+    if (value === undefined)
+        return undefined;
+    if (!ok(value))
+        throw new Error(`corrupt seed state ${path}: unexpected shape - repair with \`cotal ext seed --repair\` (or --reset)`);
+    return value;
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((s) => typeof s === "string");
+}
+export function readAuthority() {
+    return validate(authorityPath(), readJsonFile(authorityPath()), (v) => isStringArray(v.everSeeded));
+}
+export function readAuthorityBackup() {
+    return validate(authorityBackupPath(), readJsonFile(authorityBackupPath()), (v) => isStringArray(v.everSeeded));
+}
+export function readWitness() {
+    return validate(witnessPath(), readJsonFile(witnessPath()), (v) => v.initialized === true && typeof v.firstGeneration === "string");
+}
+export function readStamp() {
+    return validate(stampPath(), readJsonFile(stampPath()), (v) => typeof v.generation === "string");
+}
+/** The ever-seeded set unioned with its monotonic backup. A live authority that lost ids (a truncated
+ *  or partially-corrupt write that still parsed) can only SHRINK the set; the backup is a superset, so
+ *  unioning it on read means a deliberately-removed connector is never resurrected by such a loss.
+ *  Returns undefined only when BOTH are absent (the genuinely-lost case the caller must fail loud on). */
+export function everSeededUnion() {
+    const live = readAuthority()?.everSeeded;
+    const backup = readAuthorityBackup()?.everSeeded;
+    if (live === undefined && backup === undefined)
+        return undefined;
+    return new Set([...(live ?? []), ...(backup ?? [])]);
+}
+/**
+ * Persist the ever-seeded authority. The backup is updated FIRST as a monotonic UNION (old backup ∪
+ * new set), so the recovery source is always a superset of the live authority and a crash between the
+ * two writes can only lose ids from the authority (which the backup then restores), never from both.
+ * An older binary that reads this must union unknown ids, never drop them.
+ */
+export function writeAuthority(everSeeded) {
+    const prior = readAuthorityBackup()?.everSeeded ?? [];
+    const union = [...new Set([...prior, ...everSeeded])].sort();
+    writeJsonAtomic(authorityBackupPath(), { everSeeded: union });
+    writeJsonAtomic(authorityPath(), { everSeeded: [...everSeeded].sort() });
+}
+/** Write the initialization witness once (idempotent; refreshing it would erase the first-seen gen). */
+export function ensureWitness(generation) {
+    if (!readWitness())
+        writeJsonAtomic(witnessPath(), { initialized: true, firstGeneration: generation });
+}
+/** Write the version stamp LAST — the only thing that flips the fast path to "reconcile complete". */
+export function writeStamp(generation) {
+    writeJsonAtomic(stampPath(), { generation });
+}
+/** Recover a lost authority from the durable backup (for `--repair`). Undefined when even the backup
+ *  is gone — the caller REFUSES, because a witness alone cannot tell a removed connector from a
+ *  never-seeded future one. */
+export function recoverAuthorityFromBackup() {
+    const backup = readAuthorityBackup();
+    return backup ? new Set(backup.everSeeded) : undefined;
+}
+/** Move aside any seed-state file that no longer reads/validates, so a `--reset` can rebuild clean
+ *  state instead of wedging when a commit helper re-reads the same corrupt file. Returns the
+ *  quarantine paths (for reporting). `--reset` overwrites authority/backup/witness/stamp anyway; this
+ *  just guarantees the pre-write reads (e.g. {@link ensureWitness}) can't throw on a corrupt one. */
+export function quarantineCorruptSeedState() {
+    const readers = [
+        [authorityPath(), readAuthority],
+        [authorityBackupPath(), readAuthorityBackup],
+        [witnessPath(), readWitness],
+        [stampPath(), readStamp],
+    ];
+    const quarantined = [];
+    for (const [path, read] of readers) {
+        if (!existsSync(path))
+            continue;
+        try {
+            read();
+        }
+        catch {
+            const aside = `${path}.corrupt.${randomBytes(4).toString("hex")}`;
+            renameSync(path, aside);
+            quarantined.push(aside);
+        }
+    }
+    return quarantined;
+}
+//# sourceMappingURL=authority.js.map

package/dist/seed/authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.js","sourceRoot":"","sources":["../../src/seed/authority.ts"],"names":[],"mappings":"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"}

package/dist/seed/lock.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The reconcile-wide lock and the crash cursor.
+ *
+ * ONE lock guards a whole reconcile (not each `ext add` child) so an operator `ext add`/`remove`
+ * cannot interleave between seed children and strand a half-applied refresh decision. It rides the
+ * shared crash-safe advisory-lock primitive (atomic link publish so a racer never sees a canonical
+ * lock before its owner record; serialized reclaim so no inspect→remove targets a later generation;
+ * PID + process-start liveness so a recycled PID isn't mistaken for the holder; a bounded wait on a
+ * live holder rather than a false "interrupted"; nonce-guarded release).
+ *
+ * The cursor is the SIGKILL floor: before each connector mutation the reconcile journals
+ * `{nonce, package, phase}`, and clears it only after the stamp commits. A crash mid-reconcile leaves
+ * the cursor behind; the next boot distinguishes a LIVE reconcile (lock still actively held → wait)
+ * from a DEAD one (lock stale + cursor present → fail loud, `--repair`).
+ */
+export interface ReconcileLock {
+    readonly nonce: string;
+    release(): void;
+}
+/** Acquire the reconcile lock, waiting (bounded) on a live reconcile and reclaiming a dead owner's.
+ *  A reconcile installs four connectors via npm, so the wait bound is generous. */
+export declare function acquireReconcileLock(): ReconcileLock;
+/** True while a LIVE process holds the reconcile lock (distinguishes an in-flight reconcile from a
+ *  crashed one when a cursor is present). */
+export declare function reconcileLockActive(): boolean;
+/**
+ * True iff THIS process is a genuine seed child: it carries `COTAL_EXT_SEEDING=<nonce>` +
+ * `COTAL_EXT_SEEDING_PARENT=<pid>`, and a LIVE reconcile actually holds the lock under exactly that
+ * PID and nonce. A user cannot forge this to skip the mutation lock for an arbitrary `ext add` — the
+ * bare-`=1` bypass is gone; the marker must match the live lock the parent published.
+ */
+export declare function isAuthenticSeedChild(): boolean;
+/** The mid-reconcile journal: which package is being mutated, in which phase, under which lock nonce. */
+export interface ReconcileCursor {
+    readonly nonce: string;
+    readonly package: string;
+    readonly phase: "copy" | "add";
+}
+export declare function writeCursor(cursor: ReconcileCursor): void;
+/** Read + SCHEMA-validate the cursor: a torn write, or a parsed-but-malformed one (missing/invalid
+ *  nonce, a non-official package, an unknown phase — e.g. `{}`) is corrupt, never a silent "no target"
+ *  that lets a repair clear the journal and report success while a connector is still torn. */
+export declare function readCursor(): ReconcileCursor | undefined;
+export declare function clearCursor(): void;
+/**
+ * A seed child's liveness marker. The PARENT records `pending` BEFORE it spawns (so the window never
+ * opens ownerless); the CHILD upgrades it to `live` with its own PID + start token as its first act;
+ * the parent clears it after the child exits. A `pending` marker whose parent has died is the ambiguous
+ * window — the child may or may not have started — and is resolved fail-loud, never by guessing.
+ */
+export type ChildMarker = {
+    readonly state: "pending";
+    readonly parentPid: number;
+    readonly nonce: string;
+    readonly ts: number;
+} | {
+    readonly state: "live";
+    readonly childPid: number;
+    readonly childStart?: string;
+    readonly parentPid: number;
+    readonly nonce: string;
+    readonly ts: number;
+};
+/** Parent: record intent to spawn a seed child before `spawnSync`, so a crash never leaves a gap a
+ *  concurrent repair could race through unaware. */
+export declare function writePendingChildMarker(nonce: string): void;
+/** Child: upgrade the parent's pending marker to a live one carrying this child's identity. */
+export declare function markSeedChildLive(nonce: string, parentPid: number): void;
+export declare function clearChildMarker(): void;
+export type SeedChildStatus = {
+    readonly kind: "none";
+} | {
+    readonly kind: "live";
+    readonly pid: number;
+} | {
+    readonly kind: "ambiguous";
+    readonly path: string;
+};
+/** The state of any recorded seed child, for the orphan-vs-repair decision. A `live` child (its parent
+ *  SIGKILL'd mid-install → orphan) must not be raced. A `pending` marker whose parent is gone, or a
+ *  corrupt marker, is `ambiguous` (cannot tell "never spawned" from "child delayed") and is resolved
+ *  fail-loud. A dead/recycled child is `none` (safe to proceed). */
+export declare function seedChildStatus(): SeedChildStatus;
+/**
+ * The durable maintenance-recovery obligation. A `--repair`/`--reset` writes it BEFORE it
+ * destructively quarantines a corrupt manifest/cursor, and clears it only at the final commit — so a
+ * SIGKILL after the quarantine but before the reinstalls is not forgotten: the next boot fails loud
+ * and the next repair re-derives the same obligation (rebuild the built-ins from on-disk truth, and/or
+ * reinstall+verify every seeded built-in) instead of stamping success over missing connectors.
+ */
+export interface RecoveryObligation {
+    readonly rebuildFromDisk?: boolean;
+    readonly repairAllSeeded?: boolean;
+}
+export declare function writeRecovery(obligation: RecoveryObligation): void;
+/** Read + SCHEMA-validate the recovery obligation. A parsed-but-malformed marker (`{}`, `null`, an
+ *  array, non-boolean fields, or an all-false obligation the writer never emits) is CORRUPT, not an
+ *  empty valid obligation — it must throw so `recoveryPending()` stays true and maintenance recovers
+ *  conservatively, never silently clearing the journal over still-damaged state. */
+export declare function readRecovery(): RecoveryObligation | undefined;
+/** True iff a recovery obligation is outstanding (any read failure counts — never silently ignored). */
+export declare function recoveryPending(): boolean;
+export declare function clearRecovery(): void;
+/** Quarantine a CORRUPT (unparseable) crash CURSOR aside, so a `--repair`/`--reset` read of it can't
+ *  wedge. The cursor is a journal, not a liveness signal, so moving it aside is safe; a corrupt CHILD
+ *  MARKER is deliberately NOT touched here — it is resolved by {@link seedChildStatus}'s fail-loud
+ *  (a marker we can't read might mean an installer is running). Returns the quarantine path(s). */
+export declare function sanitizeCorruptCrashState(): string[];
+//# sourceMappingURL=lock.d.ts.map

package/dist/seed/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/seed/lock.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;mFACmF;AACnF,wBAAgB,oBAAoB,IAAI,aAAa,CAUpD;AAED;6CAC6C;AAC7C,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAM9C;AAED,yGAAyG;AACzG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;CAChC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAEzD;AAED;;+FAE+F;AAC/F,wBAAgB,UAAU,IAAI,eAAe,GAAG,SAAS,CAWxD;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjK;oDACoD;AACpD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CASxE;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;oEAGoE;AACpE,wBAAgB,eAAe,IAAI,eAAe,CAmBjD;AAgBD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAElE;AAED;;;oFAGoF;AACpF,wBAAgB,YAAY,IAAI,kBAAkB,GAAG,SAAS,CAe7D;AAED,wGAAwG;AACxG,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;mGAGmG;AACnG,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAapD"}

package/dist/seed/lock.js

@@ -0,0 +1,168 @@
+import { existsSync, renameSync, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { acquireLock, inspectLock, processStartToken } from "@cotal-ai/workspace";
+import { SEED_BUILTINS, reconcileChildPath, reconcileCursorPath, reconcileLockPath, reconcileRecoveryPath, readJsonFile, writeJsonAtomic } from "./paths.js";
+/** Acquire the reconcile lock, waiting (bounded) on a live reconcile and reclaiming a dead owner's.
+ *  A reconcile installs four connectors via npm, so the wait bound is generous. */
+export function acquireReconcileLock() {
+    const held = acquireLock(reconcileLockPath(), {
+        label: "a connector reconcile",
+        waitMs: 300000,
+        onTimeout: (owner) => new Error(`another connector reconcile has held the lock for over 5 minutes (pid ${owner.pid}) - retry once it finishes, or \`cotal ext seed --repair\` if it is wedged`),
+    });
+    return { nonce: held.nonce, release: () => held.release() };
+}
+/** True while a LIVE process holds the reconcile lock (distinguishes an in-flight reconcile from a
+ *  crashed one when a cursor is present). */
+export function reconcileLockActive() {
+    return inspectLock(reconcileLockPath()).state === "active";
+}
+/**
+ * True iff THIS process is a genuine seed child: it carries `COTAL_EXT_SEEDING=<nonce>` +
+ * `COTAL_EXT_SEEDING_PARENT=<pid>`, and a LIVE reconcile actually holds the lock under exactly that
+ * PID and nonce. A user cannot forge this to skip the mutation lock for an arbitrary `ext add` — the
+ * bare-`=1` bypass is gone; the marker must match the live lock the parent published.
+ */
+export function isAuthenticSeedChild() {
+    const nonce = process.env.COTAL_EXT_SEEDING;
+    const parent = Number(process.env.COTAL_EXT_SEEDING_PARENT);
+    if (!nonce || nonce === "1" || !Number.isInteger(parent) || parent <= 0)
+        return false;
+    const found = inspectLock(reconcileLockPath());
+    return found.state === "active" && found.owner.pid === parent && found.owner.nonce === nonce;
+}
+export function writeCursor(cursor) {
+    writeJsonAtomic(reconcileCursorPath(), cursor);
+}
+/** Read + SCHEMA-validate the cursor: a torn write, or a parsed-but-malformed one (missing/invalid
+ *  nonce, a non-official package, an unknown phase — e.g. `{}`) is corrupt, never a silent "no target"
+ *  that lets a repair clear the journal and report success while a connector is still torn. */
+export function readCursor() {
+    const cursor = readJsonFile(reconcileCursorPath());
+    if (cursor === undefined)
+        return undefined;
+    if (typeof cursor.nonce !== "string" ||
+        !SEED_BUILTINS.includes(cursor.package) ||
+        (cursor.phase !== "copy" && cursor.phase !== "add")) {
+        throw new Error(`corrupt seed cursor ${reconcileCursorPath()}: unexpected shape - repair with \`cotal ext seed --repair\` (or --reset)`);
+    }
+    return cursor;
+}
+export function clearCursor() {
+    rmSync(reconcileCursorPath(), { force: true });
+}
+/** Parent: record intent to spawn a seed child before `spawnSync`, so a crash never leaves a gap a
+ *  concurrent repair could race through unaware. */
+export function writePendingChildMarker(nonce) {
+    writeJsonAtomic(reconcileChildPath(), { state: "pending", parentPid: process.pid, nonce, ts: Date.now() });
+}
+/** Child: upgrade the parent's pending marker to a live one carrying this child's identity. */
+export function markSeedChildLive(nonce, parentPid) {
+    writeJsonAtomic(reconcileChildPath(), {
+        state: "live",
+        childPid: process.pid,
+        childStart: processStartToken(process.pid),
+        parentPid,
+        nonce,
+        ts: Date.now(),
+    });
+}
+export function clearChildMarker() {
+    rmSync(reconcileChildPath(), { force: true });
+}
+/** The state of any recorded seed child, for the orphan-vs-repair decision. A `live` child (its parent
+ *  SIGKILL'd mid-install → orphan) must not be raced. A `pending` marker whose parent is gone, or a
+ *  corrupt marker, is `ambiguous` (cannot tell "never spawned" from "child delayed") and is resolved
+ *  fail-loud. A dead/recycled child is `none` (safe to proceed). */
+export function seedChildStatus() {
+    const path = reconcileChildPath();
+    let marker;
+    try {
+        marker = readJsonFile(path);
+    }
+    catch {
+        return { kind: "ambiguous", path }; // corrupt marker — never silently ignore
+    }
+    if (!marker)
+        return { kind: "none" };
+    if (marker.state === "live") {
+        if (typeof marker.childPid !== "number")
+            return { kind: "ambiguous", path };
+        return pidAliveMatching(marker.childPid, marker.childStart) ? { kind: "live", pid: marker.childPid } : { kind: "none" };
+    }
+    if (marker.state === "pending" && typeof marker.parentPid === "number") {
+        // Parent still alive ⇒ a reconcile is starting (the caller waits on the lock); parent gone ⇒ the
+        // ambiguous SIGKILL/delayed-start window.
+        return pidAliveMatching(marker.parentPid, undefined) ? { kind: "live", pid: marker.parentPid } : { kind: "ambiguous", path };
+    }
+    return { kind: "ambiguous", path };
+}
+function pidAliveMatching(pid, start) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (e) {
+        if (e.code === "ESRCH")
+            return false;
+        // EPERM ⇒ alive under another user; fall through to the start-token check.
+    }
+    if (start !== undefined) {
+        const now = processStartToken(pid);
+        if (now !== undefined && now !== start)
+            return false; // recycled PID
+    }
+    return true;
+}
+export function writeRecovery(obligation) {
+    writeJsonAtomic(reconcileRecoveryPath(), obligation);
+}
+/** Read + SCHEMA-validate the recovery obligation. A parsed-but-malformed marker (`{}`, `null`, an
+ *  array, non-boolean fields, or an all-false obligation the writer never emits) is CORRUPT, not an
+ *  empty valid obligation — it must throw so `recoveryPending()` stays true and maintenance recovers
+ *  conservatively, never silently clearing the journal over still-damaged state. */
+export function readRecovery() {
+    const recovery = readJsonFile(reconcileRecoveryPath());
+    if (recovery === undefined)
+        return undefined;
+    const shapeOk = typeof recovery === "object" &&
+        recovery !== null &&
+        !Array.isArray(recovery) &&
+        (recovery.rebuildFromDisk === undefined || typeof recovery.rebuildFromDisk === "boolean") &&
+        (recovery.repairAllSeeded === undefined || typeof recovery.repairAllSeeded === "boolean");
+    if (!shapeOk || !(recovery.rebuildFromDisk === true || recovery.repairAllSeeded === true)) {
+        throw new Error(`corrupt recovery journal ${reconcileRecoveryPath()}: expected { rebuildFromDisk?/repairAllSeeded?: boolean, at least one true } - repair with \`cotal ext seed --repair\` (or --reset)`);
+    }
+    return recovery;
+}
+/** True iff a recovery obligation is outstanding (any read failure counts — never silently ignored). */
+export function recoveryPending() {
+    try {
+        return readRecovery() !== undefined;
+    }
+    catch {
+        return true;
+    }
+}
+export function clearRecovery() {
+    rmSync(reconcileRecoveryPath(), { force: true });
+}
+/** Quarantine a CORRUPT (unparseable) crash CURSOR aside, so a `--repair`/`--reset` read of it can't
+ *  wedge. The cursor is a journal, not a liveness signal, so moving it aside is safe; a corrupt CHILD
+ *  MARKER is deliberately NOT touched here — it is resolved by {@link seedChildStatus}'s fail-loud
+ *  (a marker we can't read might mean an installer is running). Returns the quarantine path(s). */
+export function sanitizeCorruptCrashState() {
+    const aside = [];
+    const path = reconcileCursorPath();
+    if (existsSync(path)) {
+        try {
+            readCursor(); // schema-validating read: catches torn JSON AND parsed-but-malformed (e.g. `{}`)
+        }
+        catch {
+            const dest = `${path}.corrupt.${randomBytes(4).toString("hex")}`;
+            renameSync(path, dest);
+            aside.push(dest);
+        }
+    }
+    return aside;
+}
+//# sourceMappingURL=lock.js.map

package/dist/seed/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/seed/lock.ts"],"names":[],"mappings":"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"}

package/dist/seed/paths.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Filesystem layout + version identity for the connector seeding engine. Everything the reconcile
+ * writes lives under `<config>/cotal/seed/`, a sibling of the `extensions/` npm prefix — the prefix
+ * is npm-owned (a stray dir there would confuse `npm install`), the seed state is ours.
+ *
+ * The seed store is DURABLE by design: `npm install --install-links <dir>` normalizes a `file:` dep
+ * pointing at `<dir>`, so a volatile source (an `npx` `_npx` cache) would later fail to reify. We
+ * copy each shipped connector payload into `store/<generation>/<name>` and `ext add` from THAT stable
+ * path, keyed by the binary's version so a `cotal-ai` upgrade lands a fresh generation.
+ */
+/** The four first-party connectors, in a stable seed order. Keys of {@link OFFICIAL_CONNECTORS}. */
+export declare const SEED_BUILTINS: readonly string[];
+/** `<config>/cotal/seed` — the seed engine's own state root (NOT inside the npm prefix). */
+export declare function seedDir(): string;
+/** The monotonic ever-seeded authority: which built-ins were ever seeded (never shrinks). */
+export declare function authorityPath(): string;
+/** The durable append-only backup of the authority — the ONLY source `ext seed --repair` can
+ *  recover a lost {@link authorityPath} from (a witness alone can't tell removed from never-seeded). */
+export declare function authorityBackupPath(): string;
+/** The initialization witness: proof the seeder ever ran here (distinguishes a pristine prefix from
+ *  one whose authority was lost). Written after the authority, before the stamp. */
+export declare function witnessPath(): string;
+/** The version stamp, written LAST: the generation the last reconcile completed for. A boot whose
+ *  stamp equals the current generation short-circuits (after the health preamble). */
+export declare function stampPath(): string;
+/** The reconcile-wide lock DIRECTORY (shared advisory-lock primitive: atomic `mkdir` publish, PID +
+ *  process-start liveness, bounded wait, dead-owner reclaim). */
+export declare function reconcileLockPath(): string;
+/** The durable reconcile cursor `{nonce, package, phase}`: a partial-reconcile journal a crashed
+ *  (SIGKILL) run leaves behind, so the next boot fails loud instead of silently proceeding. */
+export declare function reconcileCursorPath(): string;
+/** The seed-child liveness marker `{pid, start, ts}`: a validated `ext add` seed child writes it
+ *  before it mutates the prefix and clears it on exit, so a reclaim/repair after a parent SIGKILL can
+ *  refuse to race an orphaned child that is still installing. */
+export declare function reconcileChildPath(): string;
+/** The durable maintenance-recovery obligation `{rebuildFromDisk?, repairAllSeeded?}`: a `--repair`/
+ *  `--reset` writes it BEFORE it destructively quarantines a corrupt manifest/cursor, so a SIGKILL
+ *  after the quarantine but before the reinstalls doesn't forget that the built-ins must be rebuilt
+ *  from disk (or all reinstalled). Cleared only at the final commit. */
+export declare function reconcileRecoveryPath(): string;
+/** The durable seed store root: `<config>/cotal/seed/store`. */
+export declare function seedStoreDir(): string;
+/** A seeded connector's stable copy for one generation: `store/<generation>/<name>`. */
+export declare function seedStorePath(generation: string, name: string): string;
+/**
+ * The seed generation: this `cotal-ai` binary's version. Ties a reconcile-refresh to the shipped
+ * payload changing — including the bundled `connector-core`, so a `cotal-ai` upgrade re-seeds the
+ * connectors that carry version-coupled behavior (e.g. the v0.4 lifecycle parse). Read from the
+ * nearest `package.json` above the entry script (`cotal-ai` published, or `bin/package.json` in a
+ * dev `tsx bin/cotal.ts` run). Fails loud if unreadable — a generation-less seed can't gate refresh.
+ */
+export declare function seedGeneration(): string;
+/**
+ * The shipped payload directory for one built-in connector — the source the reconcile copies into the
+ * durable store. Dev resolves `extensions/<pkg-dir>` from this module's location (NEVER `cwd`);
+ * published resolves `<cotal-ai>/seeded-connectors/<name>` beside the entry (the `bin` prepublish
+ * copy). Fails loud if neither carries a `package.json` — a build missing its seeded connectors.
+ */
+export declare function shippedSourceDir(name: string): string;
+/** Atomically write JSON (temp-then-rename, exclusive temp — never follows a pre-planted symlink),
+ *  the same durability `writeLaunchSpec`/manifest writes use. Creates the parent dir. */
+export declare function writeJsonAtomic(path: string, value: unknown, mode?: number): void;
+/** Read + parse a JSON state file. Returns undefined when absent; throws (loud) on corrupt JSON — a
+ *  seed-state file is never silently treated as missing (that would resurrect removed connectors). */
+export declare function readJsonFile<T>(path: string): T | undefined;
+//# sourceMappingURL=paths.d.ts.map

package/dist/seed/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/seed/paths.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AAEH,oGAAoG;AACpG,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAqC,CAAC;AAEjF,4FAA4F;AAC5F,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;wGACwG;AACxG,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;oFACoF;AACpF,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;sFACsF;AACtF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;iEACiE;AACjE,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;+FAC+F;AAC/F,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;iEAEiE;AACjE,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;wEAGwE;AACxE,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,gEAAgE;AAChE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAcvC;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;yFACyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,SAAQ,GAAG,IAAI,CAMhF;AAED;sGACsG;AACtG,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAa3D"}