looply-cli 0.0.0-stage → 0.2.0

package/dist/coordinator-state.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.homesFor = homesFor;
+exports.goalsFor = goalsFor;
+exports.runsFor = runsFor;
+exports.workspacesFor = workspacesFor;
+exports.holdsFor = holdsFor;
+exports.surfacesHeldFor = surfacesHeldFor;
+exports.gatherScheduleState = gatherScheduleState;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const git_driver_1 = require("./git-driver");
+const workspace_1 = require("./workspace");
+const workspace_quarantine_1 = require("./workspace-quarantine");
+const run_lease_1 = require("./run-lease");
+const surface_lease_1 = require("./surface-lease");
+const integration_runtime_1 = require("./integration-runtime");
+const lane_claims_1 = require("./lane-claims");
+/**
+ * F28 (B13): where each goal's plan lives, keyed `goalId@version` — the checkout named by the
+ * NEWEST `claims` record for that goal and version, matched to a checkout that still exists.
+ * The newest decides: when its checkout is gone, so is the plan, and the goal has no home.
+ *
+ * ⚠️ PATHS ARE COMPARED AS THE FILESYSTEM COMPARES THEM — case-insensitively on Windows — and
+ * the answer is the scheduler's own spelling of the checkout, so its match is exact.
+ */
+function homesFor(cwd, workspaces) {
+    const norm = (p) => (process.platform === 'win32' ? (0, node_path_1.resolve)(p).toLowerCase() : (0, node_path_1.resolve)(p));
+    const byPath = new Map(workspaces.map((w) => [norm(w.path), w.path]));
+    const out = new Map();
+    for (const r of (0, lane_claims_1.readLaneClaims)(cwd)) {
+        if (r.kind !== 'claims')
+            continue;
+        const key = `${r.goalId}@${r.goalVersion}`;
+        const path = r.workspace === undefined ? undefined : byPath.get(norm(r.workspace));
+        if (path === undefined)
+            out.delete(key);
+        else
+            out.set(key, path);
+    }
+    return out;
+}
+/**
+ * Which goals the scheduler may consider, and when each became eligible.
+ *
+ * ⚠️ `queuedAt` IS `updatedAt`, WHICH IS THE HONEST APPROXIMATION AND IS SAID
+ * SO RATHER THAN LEFT TO BE FOUND. A goal has no "became eligible" timestamp;
+ * what it has is when it last changed, which for an authorized goal that has
+ * not run is when a person authorized it. The age boost is monotone in this
+ * value, so the anti-starvation bound holds whatever it is anchored to.
+ *
+ * ⚠️ AND THE OLD VERSION OF THIS SENTENCE WAS WRONG IN A WAY WORTH KEEPING. It
+ * said an inaccurate anchor "costs fairness between two goals, not liveness" —
+ * true of an anchor that is merely wrong, and false of the one the code
+ * actually produced, which was the epoch. See `queuedAt` below.
+ */
+function goalsFor(store, autonomy, 
+/**
+ * The goal ids whose work has been published to the integration ref.
+ *
+ * ⚠️ ABSENT IS UNKNOWN, AND THE SCHEDULER READS UNKNOWN AS NOT INTEGRATED
+ * — but only when the programme says it integrates. A project with no lane
+ * never consults it, which is why passing nothing is safe for every caller
+ * that had none.
+ */
+integrated) {
+    /**
+     * 🔴 THE AUTONOMY GRANT IS A SECOND STORE, AND READING IT OFF `Goal.state`
+     * WAS WHAT MADE THE SCHEDULER A NO-OP.
+     *
+     * `GoalState` is `draft | active | abandoned`. `authorized` and `satisfied`
+     * live in `GOAL_AUTONOMY_STATES`, in the autonomy store. Copying `g.state`
+     * into a field the scheduler compared against `'authorized'` matched nothing,
+     * on every goal, for ever — and no test noticed because every fixture
+     * invented `state: 'authorized'` for itself.
+     *
+     * ⚠️ AND THE MATCH IS ON GOAL VERSION TOO. A grant never follows a goal to a
+     * new version — that is the store's own rule — so a grant for version 2 must
+     * not authorise version 3, which is the amendment somebody made precisely
+     * because they wanted it looked at again.
+     */
+    const grants = autonomy?.all() ?? [];
+    /**
+     * 🔴 `find` TAKES THE FIRST ROW, AND NOTHING PRUNES A SETTLED GRANT — SO A
+     * RE-AUTHORIZED GOAL SILENTLY NEVER RAN.
+     *
+     * A goal can be authorized, satisfied, and authorized again at the same
+     * version: a person re-opens a pursuit that was declared finished. Both rows
+     * stay in the store — settling writes state, it does not delete — and this
+     * took whichever the store happened to list first. When that was the
+     * `satisfied` one, the goal read as satisfied for ever: never a candidate,
+     * never started, and it also silently SATISFIED every dependency on it, so
+     * the goals waiting behind it started against work that had not been redone.
+     *
+     * ⚠️ THE PRECEDENCE IS EXPLICIT RATHER THAN POSITIONAL. `authorized` beats
+     * every other state, because a live grant is a person saying "go" and no
+     * older row outranks it. `satisfied` is preferred next, since a finished
+     * pursuit that was never re-opened is genuinely finished. Anything else —
+     * cancelled, expired — comes last and means "not startable", which is the
+     * direction that cannot spend somebody's evening on a stale row.
+     */
+    const RANK = { authorized: 0, satisfied: 1 };
+    const stateOf = (id, version) => {
+        const mine = grants.filter((a) => a.goalId === id && a.goalVersion === version);
+        if (mine.length === 0)
+            return null;
+        let best = mine[0];
+        for (const g of mine) {
+            if ((RANK[g.state] ?? 9) < (RANK[best.state] ?? 9))
+                best = g;
+        }
+        return best.state;
+    };
+    return store.all().map((g) => ({
+        id: g.id,
+        version: g.version,
+        state: g.state,
+        autonomy: stateOf(g.id, g.version),
+        ...(g.dependsOn === undefined ? {} : { dependsOn: g.dependsOn }),
+        ...(integrated === undefined ? {} : { integrated: integrated.has(g.id) }),
+        ...(g.priority === undefined ? {} : { priority: g.priority }),
+        /**
+         * 🔴 THE SURFACE GATE READ A FIELD THIS MAP NEVER WROTE.
+         *
+         * `Goal.surfaces` exists, `ScheduleGoal.surfaces` exists, `decideSchedule`
+         * refuses a goal whose surfaces are held — and the one function that turns
+         * the first into the second dropped it. MEASURED: a goal declaring
+         * `src/app` came out of `goalsFor` with no `surfaces` key at all, so
+         * `surfacesHeldFor` iterated an empty wanted-set, `surfacesHeld` was `{}`
+         * on every cadence, and two goals over the same directory were placed
+         * together exactly as if neither had declared anything.
+         *
+         * The gate was not weak. It was reading a field nobody filled in.
+         */
+        ...(g.surfaces === undefined ? {} : { surfaces: g.surfaces }),
+        ...(g.kind === undefined ? {} : { kind: g.kind }),
+        /**
+         * ⚠️ AN UNPARSEABLE TIMESTAMP IS THE LEAST URGENT, NOT THE MOST.
+         *
+         * This was `Date.parse(g.updatedAt) || 0`, and NaN||0 is 0 — the Unix
+         * epoch, which the age boost reads as fifty-six years of waiting. MEASURED:
+         * a goal with `updatedAt: ''` scored 1,987,288 and took the only slot ahead
+         * of a priority-100 goal from a minute ago, with a reason line reporting
+         * the number as if it were earned. The comment claimed an inaccurate anchor
+         * "costs fairness, not liveness"; the fallback was the exact inverse of
+         * safe. `now` is the anchor for an unknown one: brand new, and it ages
+         * normally from here.
+         */
+        queuedAt: Number.isFinite(Date.parse(g.updatedAt)) ? Date.parse(g.updatedAt) : Date.now(),
+    }));
+}
+/**
+ * The runs in flight, from the registry the bound already uses.
+ *
+ * ⚠️ ACTIVE ONLY. An orphaned record is a crashed run: counting it would hold
+ * capacity a dead process is not using, and the reaper is what clears it.
+ */
+function runsFor(registry) {
+    return registry
+        .list()
+        .filter((e) => e.kind === 'active')
+        .map((e) => ({
+        runId: e.record.runId,
+        goalId: goalOfRun(e.record.stateDir),
+        startedAt: Date.parse(e.record.startedAt) || 0,
+        workspace: e.record.workspace,
+        /**
+         * M4-2 — PREEMPTIBILITY IS A FACT ABOUT WHO ASKED FOR THE RUN, and the
+         * record now carries it. A machine-started run (`startedBy: 'machine'`,
+         * written by the run from the launcher's `--autonomous`) may be asked to
+         * stop at its round boundary; a run a person started may not; a record
+         * from before the fact existed has no `startedBy` and is a person's.
+         * Acting on the scheduler's `preempt` is the daemon's, behind
+         * `machine.preemption` — off, this fact changes nothing.
+         */
+        preemptible: e.record.startedBy === 'machine',
+    }));
+}
+/**
+ * The checkouts the machine could hand out, and their state.
+ *
+ * ⚠️ QUARANTINED IS ITS OWN ANSWER, not "busy". A busy workspace frees itself
+ * when its run ends; a quarantined one never does, and a scheduler that could
+ * not tell them apart would wait for ever on a directory a person has to look
+ * at.
+ */
+function workspacesFor(cwd, registry, home = (0, node_os_1.homedir)()) {
+    const root = (0, workspace_1.workspacesRoot)(cwd, home);
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const path = (0, node_path_1.join)(root, name);
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(path, git_driver_1.STATE_DIR)))
+            continue;
+        const held = (0, workspace_quarantine_1.quarantineOf)(cwd, path);
+        if (held !== null) {
+            out.push({ path, state: 'quarantined' });
+            continue;
+        }
+        out.push({ path, state: (0, workspace_1.checkoutBusy)((0, node_path_1.join)(path, git_driver_1.STATE_DIR, 'state')) ? 'busy' : 'idle' });
+    }
+    // Deterministic: the scheduler hands out idle checkouts in this order, and
+    // two ticks over one machine must agree.
+    return out.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+/**
+ * The holds, flattened.
+ *
+ * ⚠️ THE COORDINATOR EVALUATES NO DETECTORS. It asks the store which goals are
+ * held and takes the answer. A scheduler that re-derived a hold would be a
+ * second brake with its own opinion, and the two would disagree exactly when
+ * it mattered.
+ */
+function holdsFor(safety, goals) {
+    if (safety === null)
+        return [];
+    /**
+     * 🔴 AN UNREADABLE HISTORY HOLDS EVERYTHING — IT USED TO HOLD NOTHING.
+     *
+     * MEASURED: a cold store whose `open()` answers `unreadable` makes every
+     * `activeIncident` return null, so this returned `[]`, so `decideSchedule`
+     * saw no holds and emitted `start`. The machine started a goal it could not
+     * show was safe to start — while the daemon had already PRINTED that autonomy
+     * would hold, because the sibling seam a few lines away in `daemon-cmd` gets
+     * this right and refuses.
+     *
+     * `loop-safety-store` says so itself, above `activeIncident`: "an unreadable
+     * file answers null … the caller treats an unreadable store as a hold in its
+     * own right, because a machine that cannot read its safety history must not
+     * spend a night on the assumption that it is empty." One caller applied that
+     * rule and one did not, and the one that did not was the new one.
+     */
+    if (!safety.readable()) {
+        return goals.map((g) => ({
+            goalId: g.id,
+            goalVersion: g.version,
+            because: 'this machine cannot read its own loop-safety history, so it cannot show this goal is not held',
+        }));
+    }
+    const out = [];
+    for (const g of goals) {
+        const incident = safety.activeIncident(g.id, g.version);
+        if (incident !== null) {
+            out.push({ goalId: g.id, goalVersion: g.version, because: incident.because });
+        }
+    }
+    return out;
+}
+/**
+ * WHICH SURFACES ARE HELD RIGHT NOW, AND BY WHICH RUN.
+ *
+ * 🔴 THE SCHEDULER'S SURFACE GATE WAS DEAD CODE. `decideSchedule` has a
+ * `waitingOn: 'surface'` branch — written, specced, and unreachable, because
+ * NOTHING in production ever populated `surfacesHeld`. So two goals declaring
+ * the same directory were both started in one tick, and the only thing standing
+ * between them was the surface lease refusing the second run AFTER it had been
+ * spawned, a workspace assigned and a model paid for.
+ *
+ * ⚠️ THE COORDINATOR ONLY LOOKS. It reports what the leases say; acquiring is
+ * still the launcher's business, in a total order, all-or-nothing, before the
+ * run starts. This is the cheap check that avoids paying for the expensive one.
+ *
+ * ⚠️ AND IT IS AN OPTIMISATION, NOT THE GUARANTEE. The lease is the guarantee —
+ * this is read at decision time and the world moves. A goal that slips through
+ * meets the lease and is refused there, which is exactly where it was refused
+ * before this existed.
+ */
+function surfacesHeldFor(cwd, goals, now) {
+    const out = {};
+    const wanted = new Set();
+    for (const g of goals)
+        for (const s of g.surfaces ?? [])
+            wanted.add(s);
+    for (const surface of wanted) {
+        try {
+            const holder = (0, surface_lease_1.holderOf)(cwd, surface, now);
+            if (holder !== null)
+                out[surface] = holder.runId;
+        }
+        catch {
+            /**
+             * ⚠️ A SURFACE THIS CANNOT READ IS LEFT UNREPORTED, and that is safe in
+             * the one direction that matters: the scheduler then does not wait on it,
+             * the run is started, and `acquireSurfaces` — which treats an unreadable
+             * claim as a HOLDER — refuses it there. The guarantee is the lease.
+             */
+        }
+    }
+    return out;
+}
+/**
+ * Which goal a run is for, from its own lease.
+ *
+ * ⚠️ THE LEASE, NOT THE REGISTRY RECORD. `RunRecord` carries no goal — it is
+ * about a CHECKOUT and a process — while the lease is what the run wrote about
+ * what it is doing. A run bound to nothing answers the empty string, which no
+ * goal matches, so an unbound run holds capacity without ever being confused
+ * for one of the goals being scheduled.
+ */
+function goalOfRun(stateDir) {
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)((0, run_lease_1.leasePathIn)(stateDir), 'utf8'));
+        return typeof raw.goalId === 'string' ? raw.goalId : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Everything the tick needs, read once. */
+function gatherScheduleState(cwd, deps) {
+    const home = deps.home ?? (0, node_os_1.homedir)();
+    /**
+     * WHICH GOALS HAVE ACTUALLY REACHED THE LANE, read from the attempt log the
+     * integrator already writes — not inferred, and not asked of the goal store,
+     * which knows nothing about branches.
+     *
+     * ⚠️ AN ATTEMPT COUNTS ONLY WHEN IT PUBLISHED. A candidate that was
+     * validated and refused put nothing on the branch, so it satisfies nothing.
+     */
+    const integrated = deps.integrates === true
+        ? new Set((0, integration_runtime_1.readAttempts)(cwd)
+            .filter((a) => a.published !== undefined && typeof a.goalId === 'string')
+            .map((a) => a.goalId))
+        : undefined;
+    const workspaces = workspacesFor(cwd, deps.registry, home);
+    // F28: where each goal's plan lives, and which grants are only holding.
+    const planHomes = homesFor(cwd, workspaces);
+    const goals = goalsFor(deps.goals, deps.autonomy, integrated).map((g) => {
+        const at = planHomes.get(`${g.id}@${g.version}`);
+        const held = deps.held?.has(g.id) === true;
+        const awaiting = deps.advised !== undefined && !deps.advised.has(`${g.id}@${g.version}`);
+        return at === undefined && !held && !awaiting
+            ? g
+            : { ...g, ...(at === undefined ? {} : { home: at }), ...(held ? { held: true } : {}), ...(awaiting ? { awaitingAdvice: true } : {}) };
+    });
+    const runs = runsFor(deps.registry);
+    /**
+     * 🔴 A RUN WHOSE GOAL CANNOT BE READ MAKES EVERY START UNSAFE.
+     *
+     * `goalOfRun` answers `''` when the lease will not parse — a torn write, a
+     * permissions change, a run that has not written it yet — and `''` matches no
+     * goal. So a live run working goal X was reported as bound to nothing, the
+     * `running` map had no entry for X, and the scheduler started X A SECOND
+     * TIME: two checkouts, two agent processes, two sets of commits on one goal.
+     * That is the exact outcome the daemon lock exists to prevent, reached
+     * without any second coordinator being involved.
+     *
+     * ⚠️ SO THE WHOLE TICK HOLDS, NOT JUST THAT GOAL — because the unreadable
+     * lease is precisely the thing that stops us knowing WHICH goal to protect.
+     * It is a hold for one tick: the next one re-reads, and a run that was
+     * mid-write has finished by then.
+     */
+    const blind = runs.some((r) => r.goalId === '');
+    return {
+        now: deps.now(),
+        goals,
+        runs,
+        workspaces,
+        capacity: deps.capacity,
+        // What the leases say, so the scheduler's surface gate is reachable at all.
+        surfacesHeld: surfacesHeldFor(cwd, goals, deps.now()),
+        ...(deps.integrates === undefined ? {} : { integrationRequired: deps.integrates }),
+        holds: blind
+            ? goals.map((g) => ({
+                goalId: g.id,
+                goalVersion: g.version,
+                because: 'a run is in flight whose goal this machine cannot read, so it cannot show that starting ' +
+                    'anything would not start the same goal twice',
+            }))
+            : holdsFor(deps.safety, goals),
+    };
+}
+//# sourceMappingURL=coordinator-state.js.map

package/dist/coordinator-state.js.map

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

package/dist/coordinator.d.ts

@@ -0,0 +1,95 @@
+import { type ScheduleAction, type ScheduleCapacity, type ScheduleGoal, type ScheduleHold, type ScheduleProposal, type ScheduleRun, type ScheduleWorkspace } from '@looply/core';
+/**
+ * THE COORDINATOR TICK: GATHER, DECIDE, RECORD. IT EXECUTES NOTHING.
+ *
+ * ⚠️ WHAT THIS FILE MAY NOT IMPORT, AND A SPEC ENFORCES IT: `model-transport`,
+ * `agent-*`, `prover`, `providers`. A scheduler that could reach a model would
+ * be the brain, and the brain is Phase 7 and optional. The decision itself is
+ * `decideSchedule` in core — pure, clockless, and testable with the executor
+ * deleted from the build.
+ *
+ * ⚠️ AND IT IS ONE MORE JOB IN THE DAEMON'S EXISTING LOOP, NOT A PROCESS. The
+ * loop is already deterministic and single-threaded with pluggable jobs and
+ * `tick = min(all cadences)`; its errors are caught per job, so a coordinator
+ * that throws cannot reject the loop.
+ */
+/** Everything the tick needs, read from stores by the caller. */
+export interface CoordinatorInput {
+    readonly now: number;
+    readonly goals: readonly ScheduleGoal[];
+    readonly runs: readonly ScheduleRun[];
+    readonly workspaces: readonly ScheduleWorkspace[];
+    readonly capacity: ScheduleCapacity;
+    readonly holds: readonly ScheduleHold[];
+    /**
+     * Which surfaces are held, and by which run.
+     *
+     * 🔴 THE SCHEDULER'S SURFACE GATE WAS DEAD CODE WITHOUT THIS. `decideSchedule`
+     * has a `waitingOn: 'surface'` branch that nothing could ever reach, so two
+     * goals declaring the same directory were both started in one tick and the
+     * only thing between them was the surface lease refusing the second AFTER a
+     * workspace had been assigned and a model paid for.
+     */
+    readonly surfacesHeld?: Readonly<Record<string, string>>;
+    /**
+     * Does this programme integrate, so that finishing locally is not finishing?
+     *
+     * 🔴 WITHOUT THIS THE SCHEDULER'S INTEGRATION RULE IS DEAD CODE, which is
+     * the shape this repository keeps writing tests about. `decideSchedule` has a
+     * branch that refuses to start a dependent on a predecessor that never
+     * reached the lane, and it can only ever fire if somebody reports that the
+     * lane exists.
+     */
+    readonly integrationRequired?: boolean;
+    readonly proposals?: readonly ScheduleProposal[];
+}
+export type TickResult = {
+    readonly ok: true;
+    readonly actions: readonly ScheduleAction[];
+}
+/** The tick did not happen. Nothing was decided and nothing was recorded. */
+ | {
+    readonly ok: false;
+    readonly because: string;
+};
+/**
+ * Where a project's schedule decisions are appended.
+ *
+ * 🔴 MACHINE-LEVEL, NOT `.looply/state/`. The coordinator schedules ACROSS N
+ * workspaces; a per-workspace path would put the machine-wide decision log
+ * inside one arbitrary workspace's state directory, where a `worktree remove`
+ * deletes it and a second workspace cannot read it. That is the same mistake
+ * Phase 2 spent two steps undoing for the rails ledgers, and it is not made
+ * twice: this sits beside them, under the repository's identity.
+ */
+export declare function schedulePath(cwd: string, home?: string): string;
+/**
+ * Append one decided action, BEFORE it is acted on.
+ *
+ * 🔴 LED BY A NEWLINE, which is the only multi-writer-safe append idiom in this
+ * tree. A crash part-way through a write leaves a fragment with no trailing
+ * newline; the next record appended straight onto it would make the two one
+ * unparseable line, so a single torn write would cost TWO decisions rather than
+ * one. Leading each record means a fragment ends up alone on its line and is
+ * skipped by itself. `loop-safety-store` worked this out first and wrote down
+ * why; this follows it rather than rediscovering it.
+ *
+ * ⚠️ BEFORE, NOT AFTER. A crashed coordinator's decisions have to be replayable,
+ * and a log written after the act cannot say what was decided but not done.
+ */
+export declare function recordActions(cwd: string, actions: readonly ScheduleAction[], at: string, home?: string): void;
+/**
+ * One tick.
+ *
+ * 🔴 IT REFUSES WITHOUT THE LOCK. See `daemon-lock.ts`: two coordinators reading
+ * the same Runs at the same moment both see the same idle capacity and both
+ * emit `start` for the same goal, and the machine runs it twice — two
+ * checkouts, two agent processes, twice the spend — with nothing in either
+ * log saying the other existed.
+ *
+ * ⚠️ THE LOCK IS ONLY INSPECTED HERE. Taking it is the daemon's business, done
+ * once at startup and held for the daemon's life; a tick that took and released
+ * it would open a window between every pair of ticks.
+ */
+export declare function coordinatorTick(cwd: string, input: CoordinatorInput, home?: string): TickResult;
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../src/coordinator.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEhB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAItB;;;;;;;;;;;;;GAaG;AAEH,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAClD;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE;AACpE,6EAA6E;GAC3E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAkB,GACvB,IAAI,CAgBN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,gBAAgB,EACvB,IAAI,GAAE,MAAkB,GACvB,UAAU,CA2BZ"}

package/dist/coordinator.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulePath = schedulePath;
+exports.recordActions = recordActions;
+exports.coordinatorTick = coordinatorTick;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+const rails_home_1 = require("./rails-home");
+const daemon_lock_1 = require("./daemon-lock");
+/**
+ * Where a project's schedule decisions are appended.
+ *
+ * 🔴 MACHINE-LEVEL, NOT `.looply/state/`. The coordinator schedules ACROSS N
+ * workspaces; a per-workspace path would put the machine-wide decision log
+ * inside one arbitrary workspace's state directory, where a `worktree remove`
+ * deletes it and a second workspace cannot read it. That is the same mistake
+ * Phase 2 spent two steps undoing for the rails ledgers, and it is not made
+ * twice: this sits beside them, under the repository's identity.
+ */
+function schedulePath(cwd, home = (0, node_os_1.homedir)()) {
+    return (0, node_path_1.join)((0, rails_home_1.railsDir)(cwd, home), '..', 'schedule.jsonl');
+}
+/**
+ * Append one decided action, BEFORE it is acted on.
+ *
+ * 🔴 LED BY A NEWLINE, which is the only multi-writer-safe append idiom in this
+ * tree. A crash part-way through a write leaves a fragment with no trailing
+ * newline; the next record appended straight onto it would make the two one
+ * unparseable line, so a single torn write would cost TWO decisions rather than
+ * one. Leading each record means a fragment ends up alone on its line and is
+ * skipped by itself. `loop-safety-store` worked this out first and wrote down
+ * why; this follows it rather than rediscovering it.
+ *
+ * ⚠️ BEFORE, NOT AFTER. A crashed coordinator's decisions have to be replayable,
+ * and a log written after the act cannot say what was decided but not done.
+ */
+function recordActions(cwd, actions, at, home = (0, node_os_1.homedir)()) {
+    if (actions.length === 0)
+        return;
+    const path = schedulePath(cwd, home);
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(path, '..'), { recursive: true });
+        const lines = actions.map((a) => `\n${JSON.stringify({ ...a, at })}\n`).join('');
+        (0, node_fs_1.appendFileSync)(path, lines, 'utf8');
+    }
+    catch {
+        /**
+         * ⚠️ A LOG THAT WILL NOT WRITE DOES NOT STOP THE MACHINE, and that is a
+         * deliberate direction rather than an oversight. The alternative — refusing
+         * to schedule because a history file is unwritable — turns a full disk into
+         * a stopped project. The decisions are still returned to the caller and
+         * still printed; what is lost is the ability to replay them later.
+         */
+    }
+}
+/**
+ * One tick.
+ *
+ * 🔴 IT REFUSES WITHOUT THE LOCK. See `daemon-lock.ts`: two coordinators reading
+ * the same Runs at the same moment both see the same idle capacity and both
+ * emit `start` for the same goal, and the machine runs it twice — two
+ * checkouts, two agent processes, twice the spend — with nothing in either
+ * log saying the other existed.
+ *
+ * ⚠️ THE LOCK IS ONLY INSPECTED HERE. Taking it is the daemon's business, done
+ * once at startup and held for the daemon's life; a tick that took and released
+ * it would open a window between every pair of ticks.
+ */
+function coordinatorTick(cwd, input, home = (0, node_os_1.homedir)()) {
+    const lock = (0, daemon_lock_1.inspectDaemonLock)(cwd);
+    if (lock.kind !== 'mine') {
+        return {
+            ok: false,
+            because: lock.kind === 'held'
+                ? `another daemon holds this project's coordinator lock (pid ${lock.claim.pid})`
+                : lock.kind === 'ambiguous'
+                    ? `the coordinator lock cannot be read: ${lock.reason}`
+                    : 'this daemon does not hold the coordinator lock',
+        };
+    }
+    const state = {
+        now: input.now,
+        goals: input.goals,
+        runs: input.runs,
+        workspaces: input.workspaces,
+        capacity: input.capacity,
+        holds: input.holds,
+        ...(input.surfacesHeld === undefined ? {} : { surfacesHeld: input.surfacesHeld }),
+        ...(input.integrationRequired === undefined ? {} : { integrationRequired: input.integrationRequired }),
+    };
+    const actions = (0, core_1.decideSchedule)(state, input.proposals ?? []);
+    recordActions(cwd, actions, new Date(input.now).toISOString(), home);
+    return { ok: true, actions };
+}
+//# sourceMappingURL=coordinator.js.map

package/dist/coordinator.js.map

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

package/dist/cursor-store.d.ts

@@ -0,0 +1,53 @@
+import type { LedgerFs } from './ledger-store';
+/**
+ * How far the server has confirmed each run — `cursor.json` under the state dir.
+ *
+ * DESIGN §3.2 specifies this file and nothing ever wrote it. Acknowledged heads
+ * lived only in `EventUploader.acked`, a Map that dies with the process, and
+ * nothing replayed the ledger afterwards. So an event appended while the server
+ * was away, or buffered when the run exited, stayed on disk and never reached
+ * the server — for good. The ledger was complete and the mirror was silently
+ * short, which is exactly the failure the ledger exists to make impossible.
+ *
+ * What is stored is the greatest **contiguous** seq per run that the server has
+ * confirmed holding. Contiguous is the load-bearing word — see
+ * `EventUploader.durableCursors`.
+ */
+export interface CursorFile {
+    version: 1;
+    /** runId → the highest seq below which nothing is missing. */
+    runs: Record<string, number>;
+}
+export declare class CursorStore {
+    private readonly stateDir;
+    private readonly fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private cursors;
+    private readable;
+    constructor(stateDir: string, fs: LedgerFs);
+    private get path();
+    /**
+     * Read what is on disk.
+     *
+     * A file that cannot be read is treated as no cursor at all, which replays
+     * more than necessary. That is the safe direction: ingest is idempotent on
+     * `(runId, seq)`, so the cost of replaying too much is duplicates the server
+     * discards, while the cost of trusting a cursor that is too high is events
+     * nothing will ever send again.
+     */
+    open(): Promise<'ok' | 'unreadable'>;
+    all(): Record<string, number>;
+    headFor(runId: string): number;
+    /**
+     * Move the cursors forward and write them down.
+     *
+     * Monotonic by construction: a lower number is ignored rather than written.
+     * Acknowledgements can arrive out of order after a retry, and a cursor that
+     * went backwards would re-send events the server already holds — harmless —
+     * but one that could be *lowered by a stale ack* and then raised by a partial
+     * one could skip a gap, which is not.
+     */
+    advance(next: Record<string, number>): Promise<void>;
+}
+//# sourceMappingURL=cursor-store.d.ts.map

package/dist/cursor-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-store.d.ts","sourceRoot":"","sources":["../src/cursor-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,qBAAa,WAAW;IAQpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAQ;gBAGL,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAG/B,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC;IA0B1C,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAI7B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI9B;;;;;;;;OAQG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAwB3D"}