looply-cli 0.0.0-stage → 0.3.0

package/dist/run-cmd.d.ts

@@ -0,0 +1,359 @@
+import type { RunDelivery } from './run-refusal-marks';
+import { type RunRefusalCode, type Item, type ItemCrossRepoContext } from '@looply/core';
+import { type LooplyConfig } from './config';
+import { type AnyEventInput } from './ledger-store';
+import { type RepairContext, type RunSummary } from './round-runner';
+import type { AnsweredQuestionView, PartialQuestionBody } from '@looply/core';
+import { type ApprovalResolutionContext } from './approval-resolution';
+import { type GovernedActionResultContext } from './governed-run';
+/**
+ * The composition root for `looply run`.
+ *
+ * Everything below this line was already built and unit-tested in isolation;
+ * none of it could be reached from the command line, which meant the product
+ * was a library. This file is the wiring, and it is deliberately the only place
+ * that knows both how to spawn a coding agent and where the state directory
+ * lives.
+ */
+/**
+ * The protected calls a test may make fail, to exercise teardown for real.
+ *
+ * 🔴 THE `holding()` GUARD HAD A SOURCE PIN AND ONE RUNTIME TEST. A pin shows
+ * the guard is written; it cannot show the hold is given back. Five of the six
+ * protected sites had no way to be made to fail without modifying production
+ * code, so five of the six were unproven — including the last one, which is the
+ * only place a run holds SURFACES and an OPEN BUDGET RESERVATION at once.
+ *
+ * ⚠️ NOT REACHABLE FROM ARGV, CONFIG, OR THE ENVIRONMENT. This is a programmatic
+ * option on `RunOptions`, in the same way every other seam in this file is
+ * injected; `bin.ts` never sets it, so no flag, no project setting and no worker
+ * can ask for it. Production always calls the real dependency.
+ *
+ * ⚠️ AND IT INJECTS ONLY THE FAILURE. `holding()`, `releaseHold`, the
+ * settlement and the whole cleanup path are the real ones — mocking any of them
+ * would be mocking the thing under test.
+ */
+export type RunFaultSite = 'startMarks.load' | 'queue.open' | 'adoptGoalItems' | 'applyRecovery' | 'acquireSurfaces' | 'exemptionStore.open';
+export interface RunOptions {
+    cwd: string;
+    config: LooplyConfig;
+    /**
+     * What other repositories have published, for items that declare a need on one.
+     *
+     * 🔴 INJECTED RATHER THAN BUILT HERE. Answering it means reading every
+     * declared repository's current revision with git and the accepted set out of
+     * the compatible-set store — knowledge the composition root already holds for
+     * the project-level check, and that this file has managed without. Building a
+     * second copy of it here is how the two come to disagree about what is
+     * published.
+     *
+     * Absent for every manual run of a project that declares no repositories.
+     */
+    crossRepo?: () => Promise<ItemCrossRepoContext | undefined>;
+    /** Test-only: make one protected call throw. See `RunFaultSite`. */
+    faultAt?: RunFaultSite;
+    /** Overrides `run.min_hours` for one run without editing the config. */
+    hours?: number;
+    /** Prints the plan and exits without spawning an agent. */
+    dryRun?: boolean;
+    /**
+     * The server command that asked for this run, when one did.
+     *
+     * Recorded in the lease so a redelivered `start-run` can be recognised as the
+     * one already being carried out rather than as a second request.
+     */
+    commandId?: string;
+    /**
+     * Whether this run was begun by the machine rather than by a person.
+     *
+     * Carried as a plain flag rather than an origin object: the only thing the
+     * run process needs to know about who asked is whether beginning it counts
+     * as a person saying go. Everything else about the controller — which grant,
+     * which ordinal, which attempt — is the daemon's business and never crosses
+     * into the run.
+     */
+    autonomous?: boolean;
+    /**
+     * The goal this run is for, and the version the SERVER stamped when the
+     * phone tapped Start.
+     *
+     * Both or neither. The version is not decoration: it is what proves the
+     * mirrored goal on this machine is the very one the person was looking at,
+     * which is what lets the whole happy path stay offline.
+     */
+    goalId?: string;
+    goalVersion?: number;
+    /**
+     * A PERSON AT A TERMINAL SPENDING THIS INCIDENT'S ONE RETRY.
+     *
+     * 🔴 THE WEDGE THIS EXISTS TO OPEN, MEASURED. A hold has no expiry and no
+     * `clear()`, deliberately. The only thing that discharges one is
+     * `LoopSafetyStore.override`, and until now the only caller was the daemon's
+     * `start-run` — a command a PAIRED PHONE sends. So a person who ran
+     * `looply run --goal-id G --goal-version 1` and hit a `repeated_failure` hold
+     * was told "Start it again to try once more", and starting it again hit the
+     * same fence, for ever, with no flag anywhere that would help.
+     *
+     * ⚠️ ONE RETRY, NOT "SAFETY OFF", and it is the SAME exclusive create the
+     * daemon spends. Typing this twice does not buy two attempts: the second
+     * finds the marker and is refused. The incident is marked spent rather than
+     * deleted and the observation history is untouched, so if this attempt also
+     * achieves nothing the detectors see the whole history and raise a NEW hold.
+     * There is deliberately no flag anywhere that turns the brake off.
+     */
+    tryOnceMore?: boolean;
+    /**
+     * Work to hand to the goal before the run begins. May be absent and may be
+     * empty, and both mean the same thing: start this goal on what it already
+     * owns.
+     */
+    itemIds?: string[];
+    /**
+     * The answer this run is picking up, when a person started again after one.
+     *
+     * AN ID, AND THE RUN GOES AND READS IT. What was refused, and in what words,
+     * comes from the server — the same place the person saw it — so what a model
+     * is told and what a person was shown cannot drift. Nothing about the
+     * decision travels on the command line.
+     *
+     * Present only on a goal-bound run, because the resolution is checked against
+     * the pursuit this run is actually for.
+     */
+    resumedFromApprovalId?: string;
+    /**
+     * The exact approval this Start was accepted to carry out.
+     *
+     * TRANSPORT, NEVER AUTHORITY. It is checked against a durable reservation
+     * naming this run's Start before anything is claimed; see `governed-run`.
+     */
+    governedApprovalId?: string;
+    log: (line: string) => void;
+}
+/**
+ * A run that will not start, and that retrying cannot fix.
+ *
+ * Separate from every other failure because the daemon treats the two
+ * differently: an ordinary failure leaves the start-run queued to be offered
+ * again, and a command offered again every three seconds for an hour is noise
+ * rather than resilience. Carried out of the process as an exit code, since
+ * that is the only channel a detached child has.
+ */
+export declare class RunRefused extends Error {
+    readonly code: RunRefusalCode;
+    /**
+     * The run's branch, when the refusal came from a run that had one (M5-2).
+     * Carried so the mark can name whose branch the lane must publish before a
+     * met goal's grant closes; absent on every refusal made before a branch
+     * exists, and on every site that has nothing to say about one.
+     */
+    readonly branch?: string | undefined;
+    /**
+     * What key 2 confirmed, on a `goal_satisfied` refusal only (L4b): the
+     * delivering run, the commit, and each required step's outcome. Carried to
+     * the mark so the daemon can settle the pursuit with facts, not a sentence.
+     */
+    readonly delivery?: RunDelivery | undefined;
+    /**
+     * The same refusal, for a machine.
+     *
+     * Carried BESIDE the message, never derived from it. 6A3 gave a refusal a
+     * sentence a person reads; a second machine deciding whether to spend
+     * anything more needs to tell "the goal is met" from "a person has to decide
+     * something", and those two sentences deliberately share their opening words.
+     *
+     * Every site that throws names its own code, because the code that took the
+     * branch is the only thing that knows which branch it took.
+     */
+    constructor(message: string, code?: RunRefusalCode, 
+    /**
+     * The run's branch, when the refusal came from a run that had one (M5-2).
+     * Carried so the mark can name whose branch the lane must publish before a
+     * met goal's grant closes; absent on every refusal made before a branch
+     * exists, and on every site that has nothing to say about one.
+     */
+    branch?: string | undefined, 
+    /**
+     * What key 2 confirmed, on a `goal_satisfied` refusal only (L4b): the
+     * delivering run, the commit, and each required step's outcome. Carried to
+     * the mark so the daemon can settle the pursuit with facts, not a sentence.
+     */
+    delivery?: RunDelivery | undefined);
+}
+/** What `looply run` exits with when it refuses for good. */
+export declare const EXIT_REFUSED = 3;
+/**
+ * THE ENDING OF A RUN THAT REGISTERED AND NEVER STARTED, WITH ITS REASON (M6-16).
+ *
+ * `releaseHold` below writes a bare `run.ended` for a run that took its slot
+ * and never reached its first round — a compile that produced nothing, a plan
+ * that came back empty, a refusal to start. M6-12 made the runner say why it
+ * halts; these endings never reach the runner, and until M6-16 their reason
+ * lived only in this process's log, which nobody reads: found live in M6-15,
+ * two machine Starts on a goal with nothing pickable each spent a minute
+ * compiling, ended `aborted` at zero rounds, and the server's feed showed the
+ * ending alone. The reason now travels the way the runner's does — one
+ * `alert { code: 'run-halted' }` immediately before the ending, on the same
+ * sink, so the phone reads "why" beside "ended" whichever half of the run
+ * wrote it. No reason recorded → no alert, never an invented sentence. Both
+ * writes are best-effort, each named in the log when it fails, and neither
+ * stops the hold being given back.
+ */
+export declare function writeEndingBeforeFirstRound(sink: {
+    append(input: AnyEventInput): Promise<unknown>;
+}, facts: {
+    runId: string;
+    projectId: string;
+    startedAtMs: number;
+    because: string | null;
+    now?: () => number;
+}, log: (line: string) => void): Promise<void>;
+/**
+ * The exit code for "somebody else is already executing this exact attempt".
+ *
+ * Distinct from {@link EXIT_REFUSED} on purpose, and the distinction is
+ * load-bearing. Exit 3 means the RUN decided something about the goal, and a
+ * controller may end a person's grant on it. This means nothing about the goal
+ * at all — another process got to the same attempt first — and a controller
+ * that read the two as one answer would report a goal finished because two
+ * daemons happened to tick at the same moment.
+ */
+export declare const EXIT_ATTEMPT_CLAIMED = 4;
+/** How much of a failing step's output the repair prompt carries inline. */
+export declare const REPAIR_PROMPT_OUTPUT_MAX_CHARS: number;
+/** How much of the previous patch the repair prompt carries inline, when it was not restored. */
+export declare const REPAIR_PROMPT_PATCH_MAX_CHARS: number;
+/**
+ * The previous attempt, as prose the worker can act on.
+ *
+ * Three things a repair needs and the one-line `lastFailure` never carried:
+ * WHAT refused the candidate and what it printed, WHAT the candidate changed,
+ * and WHETHER that change is in the tree now. The last is stated either way —
+ * "restored, these files" or "not restored, because …, you start from the
+ * base" — so the worker is never handed an unexplained clean tree.
+ *
+ * Bounded again here, tighter than the evidence on disk: the full logs live in
+ * the evidence directory, and a prompt is not the place for 256K of jest.
+ */
+export declare function describeRepair(repair: RepairContext): string;
+export declare function buildImplementerPrompt(item: Item, attempt: number, cfg: LooplyConfig, 
+/**
+ * What a person refused, when this run is a resume after one.
+ *
+ * Rendered as labelled prose rather than as data, and that is a safety
+ * decision rather than a stylistic one: the transcript is scanned for a
+ * structured request for authority, and the scan takes the FIRST one it
+ * finds. A prompt that illustrated the shape of such a request would be a
+ * decoy that an echoing model files for real.
+ */
+resolution?: ApprovalResolutionContext, 
+/**
+ * What a person approved that has already been DONE, when this run did it.
+ *
+ * Prose for the same reason, and the reason bites harder here: this block
+ * describes a consequential act that SUCCEEDED, and a model that read it as
+ * a template and echoed the shape back would be asking for that act again.
+ */
+governed?: GovernedActionResultContext, 
+/**
+ * What this project has already established, as labelled prose.
+ *
+ * Prose for the same reason the two blocks above are, and the reasoning is
+ * Phase 7's: a declaration of authority is a SHAPE on a structured channel,
+ * never a phrase, so nothing written here can become a request. What it must
+ * not do is show a TEMPLATE of that shape, which an echoing model could fill
+ * in for real — so memory is rendered as bulleted claims, never as data.
+ *
+ * Already sectioned and budgeted by `assembleMemoryContext`; this builder
+ * neither ranks nor trims, because one that re-decided what fits would be a
+ * second place the budget lives.
+ */
+memory?: string | null, 
+/**
+ * What the committed repository establishes about this work, from the graph.
+ *
+ * 🔴 A SEPARATE PARAMETER FROM `memory`, AND SEPARATE ALL THE WAY TO THE
+ * PROMPT. Concatenating them here would put "the repository says these files
+ * import you" under the same heading as "a person decided you must not
+ * force-push" — two different authorities, and the whole of Phase 13 is that
+ * a reader can always tell which one is speaking.
+ */
+structure?: string | null, 
+/**
+ * What the previous attempt did and what refused it, when this run saw it.
+ *
+ * 🔴 THE RETRY USED TO GET ONE LINE AND A CLEAN TREE. "gate red: step
+ * typecheck failed" was the whole briefing, and the work from the round
+ * before had been reset away without a word about it. A worker cannot
+ * repair what it has not been shown; it starts over. This renders the
+ * retained evidence — the failing step's output, the manifest, the patch or
+ * the fact that it was restored into the tree — as labelled prose.
+ *
+ * Prose, and never a template, for the same reason every block above is:
+ * the step output and the patch are fenced as text the model is to READ,
+ * and nothing here shows the shape of a structured request for authority.
+ */
+repair?: RepairContext, 
+/**
+ * WHAT THE PERSON ACTUALLY ASKED FOR, WHICH NEVER GOT THIS FAR.
+ *
+ * 🔴 THE IMPLEMENTER WAS HANDED AN ITEM TITLE. A person types a goal of up to
+ * two thousand characters; the brain compiles it into items; and this builder
+ * emitted `item.title` and nothing else — so everything they wrote about what
+ * they want, why, and what would count as done stopped at the compile step.
+ * The capability audit's E-01, and the distance between it and what the
+ * product promises is the whole reason M8 exists: eleven cycles of M6 made
+ * the AUTHORITY to pursue a goal safe, while the thing being pursued was not
+ * being carried to the model doing the work.
+ *
+ * ⚠️ IT WAS ALWAYS ONE PROPERTY AWAY. The call site reads
+ * `binding.goal.id` off a `Goal` whose `text` is, in core's words, "the
+ * user's own wording, preserved verbatim". Nothing had to be carried here;
+ * the id was taken and the text was left behind.
+ *
+ * ⚠️ PROSE, AND NEVER A TEMPLATE, for the reason every block above says it:
+ * a declaration of authority is a SHAPE on a structured channel, never a
+ * phrase, and a prompt that showed that shape would be a decoy an echoing
+ * model could fill in for real. A goal is exactly where a person might write
+ * a sentence that READS like an instruction — "and then push it" — so the
+ * block introduces the text as something THEY wrote, and carries no
+ * structured shape at all.
+ *
+ * ⚠️ NOT TRIMMED HERE. The server caps a goal at `MAX_GOAL_TEXT` where it is
+ * created, and a goal reaches this machine only through the server. A second
+ * trim here would be a second place the budget lives — the same reason
+ * `memory` is neither ranked nor trimmed by this function.
+ */
+goal?: string | null): string;
+/**
+ * A way to re-read the goal mirror from the server, if this machine has one.
+ *
+ * Deliberately not `attachSync`: that starts a sync daemon with a flush loop
+ * and a poll cadence, and it happens much further down, once the lease is
+ * held. All that is needed here is a single GET before anything is taken.
+ *
+ * Returns null when this machine is not paired, or is paired but has never
+ * registered this directory — both are ordinary states, and neither is a
+ * failure. A machine in either can still start a goal whose version its mirror
+ * already matches; it simply cannot be told about a newer one.
+ */
+/**
+ * The two question calls a run may make, and no others.
+ *
+ * ⚠️ DEFINED HERE rather than imported as the client's own types, for the
+ * reason every other capability in this file is: the narrowing IS the design,
+ * and a shape that admitted a third call would make it a comment.
+ */
+export interface PartialQuestionCapability {
+    ask(body: PartialQuestionBody & {
+        projectId: string;
+    }): Promise<{
+        id: string;
+    }>;
+    read(projectId: string, questionId: string): Promise<AnsweredQuestionView | null>;
+}
+/**
+ * Assemble and run. Returns the summary the caller prints; every transition is
+ * already on disk in the ledger by the time this resolves.
+ */
+export declare function runLoop(opts: RunOptions): Promise<RunSummary>;
+//# sourceMappingURL=run-cmd.d.ts.map

package/dist/run-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cmd.d.ts","sourceRoot":"","sources":["../src/run-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOvD,OAAO,EAGL,KAAK,cAAc,EAKnB,KAAK,IAAI,EAaT,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA6B/E,OAAO,EAGL,KAAK,aAAa,EAIlB,KAAK,UAAU,EAChB,MAAM,gBAAgB,CAAC;AAoBxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAiB9E,OAAO,EAGL,KAAK,yBAAyB,EAE/B,MAAM,uBAAuB,CAAC;AA4D/B,OAAO,EAIL,KAAK,2BAA2B,EAEjC,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,YAAY,GACZ,gBAAgB,GAChB,eAAe,GACf,iBAAiB,GACjB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;IAC5D,oEAAoE;IACpE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAcjC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW;IA1BjC;;;;;;;;;;OAUG;gBAED,OAAO,EAAE,MAAM,EACN,IAAI,GAAE,cAA8B;IAC7C;;;;;OAKG;IACM,MAAM,CAAC,EAAE,MAAM,YAAA;IACxB;;;;OAIG;IACM,QAAQ,CAAC,EAAE,WAAW,YAAA;CAIlC;AAED,6DAA6D;AAC7D,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE;IAAE,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,EACxD,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,EAC5G,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAYtC,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,QAAY,CAAC;AACxD,iGAAiG;AACjG,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA+D5D;AA6MD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,YAAY;AACjB;;;;;;;;GAQG;AACH,UAAU,CAAC,EAAE,yBAAyB;AACtC;;;;;;GAMG;AACH,QAAQ,CAAC,EAAE,2BAA2B;AACtC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;AACtB;;;;;;;;GAQG;AACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;AACzB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,EAAE,aAAa;AACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,CAyFR;AAED;;;;;;;;;;;GAWG;AACH;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,IAAI,EAAE,mBAAmB,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;CACnF;AAiID;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAqxHnE"}