@intentius/chant 0.90.0 → 0.93.0

package/dist/op/steward-points.d.ts

@@ -0,0 +1,136 @@
+/**
+ * A decision point asked inside an Op run (#2749), and in a steward's turn in
+ * particular.
+ *
+ * An Op that needs a decision (the factory's builder tier, whether to ship)
+ * calls {@link askPointInRun} from one of its activities, such as the decide
+ * activity (#2740). It asks the point through `askPoint` (ws-058,
+ * `../workspace/decide.ts`), which records the question and its answer as a
+ * record, and then:
+ *
+ * - an `answered` question returns its answer, and the Op goes on;
+ * - an `escalated` or `proposed` question is open, so the activity throws
+ *   {@link PointWait}. The executor ends the run there with status `waiting`,
+ *   as a gate ends it with `gated`: no later step runs, no `onFailure` phase
+ *   runs, and the run ledger records the question the run is waiting on.
+ *
+ * The question stays open in the workspace, where `chant workspace points
+ * --open`, MCP's `workspace-points` and hud read it, and a person answers it
+ * with `points answer`. Nothing waits in the meantime: the next run asks the
+ * same point with the same inputs, finds the answer record, and goes on. A
+ * local steward re-runs a waiting Op on the first round after its question is
+ * answered (`./operator.ts`).
+ *
+ * ## In a steward's turn
+ *
+ * A steward runs unattended, so two more rules hold when the process is a
+ * steward's turn (`./steward-turn.ts`):
+ *
+ * - The model call goes through the broker. The caller supplies the call as a
+ *   {@link BrokeredModelAsk}, which is handed the box capability to reach the
+ *   model through, and only a capability the steward declares
+ *   (`declareSteward({ capabilities })`, #2726). A steward that names none,
+ *   or holds a vault, makes no model call: the model decider is recorded as
+ *   not reached and the question goes to people.
+ * - The question is written on the `chant/lifecycle` branch, not in the
+ *   checkout (#2786): the working tree is the coding agent's, and an Op's
+ *   leased worktree goes when the run ends. `points` reads it from there
+ *   (`../workspace/answers-ledger.ts`), and a person's answer goes there too.
+ * - The question names the steward and its run in its source block, and
+ *   neither the steward's turn nor the steward's name can answer it: `points
+ *   answer` refuses inside a steward's turn (`answer-in-steward-turn`) and
+ *   leaves the asking steward out of the quorum.
+ *
+ * The question never goes to the steward's own thread: on Fountain that thread
+ * is the steward's, and nobody reads it for questions.
+ */
+import type { ModelAsk, ModelRequest, WireAnswer } from "../workspace/points.js";
+import type { QuestionView } from "../workspace/decide.js";
+import { type StewardTurn } from "./steward-turn.js";
+/** The box capability a model call goes through when the caller names none. */
+export declare const DEFAULT_INFERENCE_CAPABILITY = "inference";
+/** The open question a run stopped on, as the run ledger records it. */
+export interface WaitingPoint {
+    /** The answer record's id: what `points answer` and hud name. */
+    id: string;
+    /** The point asked. */
+    point: string;
+    /** Its state when the run stopped: `escalated` to people, or `proposed` by a model and waiting for a person to confirm it. */
+    state: "escalated" | "proposed";
+    /** The answer record, from the repository root. */
+    path: string;
+    /** What the question is about, or null. */
+    subject: string | null;
+    /** The steward whose turn asked it, or null. */
+    steward: string | null;
+}
+/** The marker {@link PointWait} carries, so a copy of core linked twice still recognises it. */
+declare const POINT_WAIT: unique symbol;
+/**
+ * Thrown by an activity whose decision point is open. Not a failure: the
+ * executor ends the run with status `waiting` (see the module doc).
+ */
+export declare class PointWait extends Error {
+    readonly question: WaitingPoint;
+    readonly [POINT_WAIT] = true;
+    constructor(question: WaitingPoint);
+}
+/** Is this a {@link PointWait}? Duck-typed on the shared symbol. */
+export declare function isPointWait(err: unknown): err is PointWait;
+/**
+ * The model call, supplied by the caller (the decide activity, #2740, or a
+ * test's stub), made through a box capability. `via.capability` is the
+ * capability to reach the model through and `via.broker` the broker the
+ * member's box block names for it, when that is known. The function holds no
+ * credential: the broker does.
+ */
+export type BrokeredModelAsk = (request: ModelRequest, via: {
+    capability: string;
+    broker: string | null;
+}) => Promise<{
+    model: string;
+    answer: WireAnswer;
+}>;
+export interface AskPointInRunOptions {
+    /** Where the workspace and the answer kind are found. */
+    cwd: string;
+    point: string;
+    inputs: unknown;
+    subject?: string;
+    /** The answer kind file, or a declared kind's name. */
+    kind?: string;
+    /** The model call. Without it, a model decider is not asked. */
+    ask?: BrokeredModelAsk;
+    /** The box capability the model call goes through. Default `inference`. */
+    capability?: string;
+    /** The broker the member's box block names for the capability, when the caller has read it. */
+    broker?: string | null;
+    /** The date written as asked_on, YYYY-MM-DD. */
+    on?: string;
+    /** The steward turn, when the caller has it. Default: this process's (`currentStewardTurn`). */
+    turn?: StewardTurn | null;
+}
+/**
+ * The {@link ModelAsk} a point is asked with. In a steward's turn the call is
+ * made only through a capability the steward declares; otherwise it throws,
+ * which the chain records as the model not being reached.
+ */
+export declare function brokeredModelAsk(ask: BrokeredModelAsk, opts: {
+    capability?: string;
+    broker?: string | null;
+    turn?: StewardTurn | null;
+    cwd: string;
+}): Promise<ModelAsk>;
+/**
+ * Ask a decision point from inside an Op run. Resolves with the answer when
+ * the question is answered, and throws {@link PointWait} when it is open.
+ * Any other problem (the points can't be read, the inputs are wrong, a model
+ * declared `unreachable: "fail"` could not answer) throws an ordinary error,
+ * which fails the step.
+ */
+export declare function askPointInRun(opts: AskPointInRunOptions): Promise<{
+    answer: string | boolean;
+    question: QuestionView;
+}>;
+export {};
+//# sourceMappingURL=steward-points.d.ts.map

package/dist/op/steward-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steward-points.d.ts","sourceRoot":"","sources":["../../src/op/steward-points.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEtE,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,cAAc,CAAC;AAExD,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,8HAA8H;IAC9H,KAAK,EAAE,WAAW,GAAG,UAAU,CAAC;IAChC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gDAAgD;IAChD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gGAAgG;AAChG,QAAA,MAAM,UAAU,eAAmC,CAAC;AAEpD;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAEtB,QAAQ,CAAC,QAAQ,EAAE,YAAY;IAD3C,QAAQ,CAAC,CAAC,UAAU,CAAC,QAAQ;gBACR,QAAQ,EAAE,YAAY;CAO5C;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,SAAS,CAE1D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,KAC/C,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gGAAgG;IAChG,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3B;AAUD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5F,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAC,CAyB7H"}

package/dist/op/steward-turn.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Whether this process is a steward's turn, and whose (#2749).
+ *
+ * A steward runs unattended. In the local form, `chant operator --steward`
+ * is the steward for as long as it runs; on Fountain, the Agent's `chant acp
+ * --steward <name>` session is. Two things read this: a decision point asked
+ * during the turn (`./steward-points.ts`), which records the steward on the
+ * question and makes its model call through the steward's brokered
+ * capability, and `points answer`, which refuses to record an answer from a
+ * steward's own turn, as the gate ledger's origin rule refuses a gate
+ * resolved on the channel that reached it.
+ *
+ * Like the gate origin (`../lifecycle/gate-origin.ts`) this is a property of
+ * the process, set once at its entry point, not a parameter threaded through
+ * every executor and activity. It is also exported to child processes as
+ * `CHANT_STEWARD`, so a `chant workspace points answer` an Op shells out to
+ * is refused the same way.
+ */
+/** The environment variable a steward's turn carries into child processes. */
+export declare const STEWARD_ENV = "CHANT_STEWARD";
+/** A steward's turn, as the process knows it. */
+export interface StewardTurn {
+    /** The steward's name. */
+    steward: string;
+    /**
+     * The box capabilities the steward reaches through the broker (#2726), or
+     * undefined when the process was told only the steward's name (a child
+     * process, or `chant acp --steward <name>`): the declaration is then read
+     * from the project's `*.op.ts` files when a model call needs it.
+     */
+    capabilities?: readonly string[];
+    /** The vault the steward holds, by name, when it is not behind a broker. */
+    vault?: string | null;
+    /** The run the steward is in, when an Op is running. */
+    run?: string;
+}
+/**
+ * Declare that this process is a steward's turn. Called once by `chant
+ * operator --steward` and `chant acp --steward`; also exports
+ * {@link STEWARD_ENV} so a child process knows it too.
+ */
+export declare function setStewardTurn(turn: StewardTurn): void;
+/**
+ * Be a steward's turn until the returned function is called, which puts back
+ * whatever was there before. `chant operator --steward` enters one per Op run,
+ * naming the run, so a question asked during it names the run too.
+ */
+export declare function enterStewardTurn(turn: StewardTurn): () => void;
+/** The steward whose turn this process is, or undefined. */
+export declare function currentStewardTurn(): StewardTurn | undefined;
+/** Forget the turn. For tests, which must not leak a steward into each other. */
+export declare function resetStewardTurn(): void;
+//# sourceMappingURL=steward-turn.d.ts.map

package/dist/op/steward-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steward-turn.d.ts","sourceRoot":"","sources":["../../src/op/steward-turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAE3C,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAGtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,IAAI,CAS9D;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,WAAW,GAAG,SAAS,CAI5D;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/op/steward.d.ts

@@ -0,0 +1,161 @@
+/**
+ * A steward's declaration (#2731): the one writer for an environment, as data
+ * core can read without any lexicon loaded.
+ *
+ * A steward runs a fixed list of Ops, each on its own `schedule` when it has
+ * one, one Op at a time. Where it runs is its form:
+ *
+ * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent on
+ *   a persistent sandbox bound to a Teammate, with a Fountain `Schedule` per
+ *   scheduled Op. A turn is one `chant run <op>` on the teammate's thread.
+ * - `local`: `chant operator --steward <name>` in the box itself, for a box
+ *   with no Fountain behind it (a docker compose box, a Sprites box). The same
+ *   Ops on the same crons, each run under its operator lease, and the steward
+ *   itself under a lease of its own so a second local operator is refused.
+ *
+ * One declaration covers both. `form` is either one of the two, or a default
+ * with per-environment exceptions, so a box whose `minimal` environment has no
+ * Fountain and whose `fountain-k3d` one does still has exactly one steward:
+ *
+ * ```ts
+ * // ops/steward.op.ts
+ * export const steward = declareSteward({
+ *   name: "box-steward",
+ *   ops: [converge, dispatch, release, upgrade],
+ *   form: { default: "local", environments: { "fountain-k3d": "fountain" } },
+ * });
+ * ```
+ *
+ * The fountain composite builds this same declaration from its own options and
+ * returns it as `declaration`, so a project that declares its steward there
+ * exports that object from an `*.op.ts` file instead of calling this function.
+ *
+ * ## Discovery
+ *
+ * A steward is discovered from the same `*.op.ts` files Ops are
+ * (`./discover.ts`), because it is chant's own run-time declaration and sits
+ * beside the Ops it runs. It is plain data with a `kind` marker, not a
+ * Declarable, so `chant build` never serializes it and a copy of core linked
+ * twice still recognises it.
+ *
+ * ## What a steward writes
+ *
+ * A steward's writes are chant writes: run, converge and gate records on the
+ * `chant/lifecycle` branch, the answer records of the decision points its
+ * Ops ask (`_answers/`, #2786), and lease refs under `refs/chant/lease/`, all made
+ * with git plumbing (`../lifecycle/git.ts`: `hash-object`, `mktree`,
+ * `commit-tree`, `update-ref`). None of them reads or writes the checkout's
+ * index or working tree, so a coding agent editing the app in the same
+ * checkout, and holding git's index lock while it commits, never collides with
+ * a steward turn. The app's files are the coding agent's; the steward does not
+ * edit them.
+ *
+ * An Op that has to change the checkout (applying a build, a workspace
+ * upgrade) says so with `changesCheckout` and runs under a work item's lease
+ * (`workLease`, #2748): its leased steps get a worktree of their own on
+ * `chant/work/<item>`. `declareSteward` refuses such an Op without the lease,
+ * and a scheduled Op whose lease leaves the item to the run.
+ */
+import type { OpConfig } from "./types.js";
+/** The entity marker a steward declaration carries. */
+export declare const STEWARD_KIND = "Chant::Steward";
+/** Where a steward runs. */
+export declare const STEWARD_FORMS: readonly ["local", "fountain"];
+export type StewardForm = (typeof STEWARD_FORMS)[number];
+/** The form a declaration asks for, as given: one form, or a default with per-environment exceptions. */
+export type StewardFormSpec = StewardForm | {
+    default: StewardForm;
+    environments?: Record<string, StewardForm>;
+};
+/** The environment a form is chosen for when none is named: the same default a run ledger uses. */
+export declare const DEFAULT_STEWARD_ENV = "local";
+/** Names a steward's lease ref and a ledger path can hold. */
+export declare const STEWARD_NAME_PATTERN: RegExp;
+/**
+ * An Op a steward runs, however the project holds it: the `Op()` declaration
+ * (config behind `.props`), or the bare config.
+ */
+export type StewardOpInput = OpConfig | {
+    props: unknown;
+};
+export interface StewardDeclarationConfig {
+    /** The steward's name. On Fountain, the Agent's and the Teammate's. */
+    name: string;
+    /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
+    ops: StewardOpInput[];
+    /** Where it runs. Default `local`. */
+    form?: StewardFormSpec;
+    /**
+     * The box capabilities its Ops reach through the box's broker (#2726), by
+     * the names the member's `box` block in the workspace declaration gives
+     * them, such as `fountain` or `inference`. A steward that names any holds no
+     * credential of its own, so it takes no `vault`.
+     */
+    capabilities?: string[];
+    /** The vault the steward holds on Fountain, by name, for a steward that isn't behind a broker. */
+    vault?: string;
+}
+/** A steward's declaration, normalised. Plain data: see the module doc. */
+export interface StewardDeclaration {
+    readonly kind: typeof STEWARD_KIND;
+    readonly name: string;
+    readonly ops: readonly OpConfig[];
+    readonly form: {
+        readonly default: StewardForm;
+        readonly environments: Readonly<Record<string, StewardForm>>;
+    };
+    /** Brokered box capabilities its Ops use (#2726). Empty when it names none. */
+    readonly capabilities: readonly string[];
+    /** The vault it holds, by name, or null. Never set together with `capabilities`. */
+    readonly vault: string | null;
+}
+/** The config inside an op, whether it arrived as a declaration or as itself. */
+export declare function stewardOpConfig(op: StewardOpInput): OpConfig;
+/** Normalise a form spec, refusing an unknown form or an environment name no ledger could hold. */
+export declare function normaliseStewardForm(steward: string, spec: StewardFormSpec | undefined): StewardDeclaration["form"];
+/**
+ * Declare a steward. Refuses what would make it more than one writer or a
+ * promise it can't keep: an Op listed twice, a schedule whose overlap isn't
+ * `skip` (a fire while a turn runs is dropped in both forms), a cron that
+ * doesn't parse, and a name a lease ref can't hold.
+ */
+export declare function declareSteward(config: StewardDeclarationConfig): StewardDeclaration;
+/** Is this value a steward declaration? Duck-typed, like `isOpEntity`. */
+export declare function isStewardDeclaration(value: unknown): value is StewardDeclaration;
+/** The form a steward takes in `env` (`local` when none is named). */
+export declare function stewardFormFor(steward: StewardDeclaration, env?: string): StewardForm;
+/**
+ * The lease a local steward holds for as long as it runs, so a second
+ * `chant operator --steward` for the same steward is refused. It sits under
+ * `refs/chant/lease/_stewards/`, beside the per-Op leases, which a leading
+ * `_` keeps out of any Op's name.
+ */
+export declare function stewardLeaseName(steward: string): string;
+/**
+ * The lease a local steward holds for as long as one of its Ops is actually
+ * running: one turn (#2750). Distinct from {@link stewardLeaseName}, which one
+ * `chant operator --steward` process holds for its whole life (renewed
+ * between ticks, released only when the process stops) — this one is taken
+ * right before a run starts and released right after it ends, whether the
+ * run is a round's scheduled tick or `chant run <op>` typed by hand. That is
+ * what makes an on-request run wait its turn behind a turn already in
+ * progress, and succeed again the moment that turn ends, rather than only
+ * once the whole steward process stops.
+ *
+ * `_turns/<name>`, not `_stewards/<name>/turn`: a git ref name is a path
+ * component in the loose-refs tree, and `refs/chant/lease/_stewards/<name>`
+ * (the lease {@link stewardLeaseName} names) already exists as a *leaf* —
+ * git refuses to also create anything *under* it (`fatal: ... exists;
+ * cannot create ...`), so nesting the turn lease inside the steward lease's
+ * own name is unusable the moment both are live at once. A sibling
+ * top-level segment sidesteps that entirely.
+ */
+export declare function stewardTurnLeaseName(steward: string): string;
+/**
+ * Pick the steward `--steward [<name>]` names, or the project's only one.
+ * Returns the steward, or the message to refuse with.
+ */
+export declare function pickSteward(stewards: Map<string, {
+    declaration: StewardDeclaration;
+}>, name: string): StewardDeclaration | string;
+//# sourceMappingURL=steward.d.ts.map

package/dist/op/steward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steward.d.ts","sourceRoot":"","sources":["../../src/op/steward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC,uDAAuD;AACvD,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,4BAA4B;AAC5B,eAAO,MAAM,aAAa,gCAAiC,CAAC;AAC5D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,yGAAyG;AACzG,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAAC;AAEjH,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,QAAsC,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,EAAE,cAAc,EAAE,CAAC;IACtB,sCAAsC;IACtC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;KAAE,CAAC;IAC/G,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,EAAE,EAAE,cAAc,GAAG,QAAQ,CAG5D;AASD,mGAAmG;AACnG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAWnH;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CAyDnF;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAWhF;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,GAAE,MAA4B,GAAG,WAAW,CAE1G;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,WAAW,EAAE,kBAAkB,CAAA;CAAE,CAAC,EAC1D,IAAI,EAAE,MAAM,GACX,kBAAkB,GAAG,MAAM,CAU7B"}

package/dist/op/types.d.ts

@@ -40,6 +40,57 @@ export interface OpConfig {
      * local one-shot executor ignores it.
      */
     schedule?: OpSchedule;
+    /**
+     * The work item this Op runs under (#2748, ws-055). The executor claims the
+     * item's work lease (`../lifecycle/work-lease.ts`) before the steps that run
+     * under it, renews it as a heartbeat while they run, stops the run when the
+     * lease is lost, and gives it back when the run ends. See
+     * {@link OpWorkLease} and `./work-lease-run.ts`.
+     */
+    workLease?: OpWorkLease;
+    /**
+     * The Op changes the checkout: it applies a build, or upgrades the
+     * workspace (#2748). Such an Op must declare {@link OpConfig.workLease}: the
+     * executor refuses to run it otherwise, and `declareSteward` refuses to list
+     * it. Its leased steps get a git worktree of their own, on the branch
+     * `chant/work/<item>`, so the change never lands in the working tree a
+     * coding agent is editing.
+     */
+    changesCheckout?: boolean;
+}
+/**
+ * The id under which a run's work lease is published to its steps (#2748):
+ * `stepOutput(WORK_LEASE_STEP_ID, "token")`, or `workLeaseOutput("token")`
+ * from `./work-lease-run.ts`. No step of an Op with a `workLease` may use it.
+ */
+export declare const WORK_LEASE_STEP_ID = "workLease";
+/**
+ * Which work item an Op runs under, and how (#2748).
+ *
+ * `item` is an id, a list of candidate ids (the first one nobody holds is
+ * claimed, as chud's dispatcher took the first ready contract nobody held), a
+ * reference to an earlier step's output that resolves to either, or omitted,
+ * in which case the run names it (`chant run <op> --work <id>`). A literal or
+ * run-time item is claimed before the first step; a referenced one right
+ * after the step that produces it. A run that finds nothing to claim (the
+ * reference resolved to nothing, or every candidate is held) ends `ok` with
+ * the rest of its steps skipped, and the claim's record says why.
+ */
+export interface OpWorkLease {
+    item?: string | string[] | StepOutputRef;
+    /**
+     * The work kind file whose member owns the lease (#2524 D7), relative to
+     * the project directory. Omitted, the lease is in the project's own ledger.
+     */
+    kind?: string;
+    /** How long a claim lasts unless renewed, as a duration ("10m"). Renewed every third of it. Default 10m. */
+    ttl?: string;
+    /**
+     * How the release records a run that ended `ok`: a reference to a step
+     * output holding a short string (`done`, `not_done`, ...). Default `done`;
+     * a failed run releases `not_done` and a gated one `gated`.
+     */
+    outcome?: StepOutputRef;
 }
 /**
  * An Op's cadence (#2120). The cron is validated at `Op()` construction by
@@ -94,6 +145,13 @@ export interface ActivityStep {
      * Default: "fastIdempotent"
      */
     profile?: ActivityProfileName;
+    /**
+     * How long one attempt may run, such as `"45m"`, in place of the
+     * profile's timeout (#2787). The profile's retry policy is kept, so a
+     * `shell` step stays one attempt. At most `MAX_STEP_TIMEOUT` (six hours); a longer
+     * wait is a gate, not a step.
+     */
+    timeout?: string;
     /**
      * Surface this activity's return value as a named run outcome.
      *

package/dist/op/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,2JAA2J;IAC3J,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,aAAa,CAAC;IACzC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4GAA4G;IAC5G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;CAC1D;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAA;CAAE,GAAG,gBAAgB,EAAE,CAI1H;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IACtC,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GACjC,CACI;IACE,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD;IACE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;CACpB,CACJ,CAAC"}

package/dist/op/work-lease-decl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The rules an Op's `workLease` and `changesCheckout` declaration keeps
+ * (#2748), with no imports beyond the Op model, so `Op()` and
+ * `declareSteward` can check them without loading the lease machinery in
+ * `./work-lease-run.ts`.
+ */
+import { type OpConfig } from "./types.js";
+/** A work item id a lease can be keyed by: the same pattern as `WORK_ITEM_ID_PATTERN` in `../lifecycle/work-lease.ts`. */
+export declare const WORK_LEASE_ITEM_PATTERN: RegExp;
+/**
+ * What is wrong with an Op's `workLease` and `changesCheckout`, or an empty
+ * list. The executor refuses to start a run with any of these, and
+ * `declareSteward` refuses to list the Op.
+ */
+export declare function workLeaseProblems(config: Pick<OpConfig, "name" | "phases" | "workLease" | "changesCheckout">): string[];
+/** Whether a run of this Op has to be told its work item (`--work <id>`). */
+export declare function workLeaseNeedsRunItem(config: Pick<OpConfig, "workLease">): boolean;
+//# sourceMappingURL=work-lease-decl.d.ts.map

package/dist/op/work-lease-decl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-lease-decl.d.ts","sourceRoot":"","sources":["../../src/op/work-lease-decl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAsB,KAAK,QAAQ,EAAwB,MAAM,SAAS,CAAC;AAElF,0HAA0H;AAC1H,eAAO,MAAM,uBAAuB,QAAsC,CAAC;AAW3E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,iBAAiB,CAAC,GAAG,MAAM,EAAE,CA6CvH;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,OAAO,CAElF"}

package/dist/op/work-lease-run.d.ts

@@ -0,0 +1,173 @@
+/**
+ * An Op run under a work item's lease (#2748, the Steward's gap 4 in #2731).
+ *
+ * An Op that declares `workLease` (`./types.ts`) runs its steps under the work
+ * lease of one work item (`../lifecycle/work-lease.ts`, ws-055). The local
+ * executor (`./local-executor.ts`) drives the {@link RunWorkLease} here:
+ *
+ * - Claim. Before the first step when the item is a literal or named by the
+ *   run (`chant run <op> --work <id>`); right after the producing step when
+ *   the item is a reference to a step's output. A list of candidates is tried
+ *   in order and the first one nobody holds is taken. When nothing can be
+ *   claimed the run ends `ok` with its remaining steps skipped, and the claim's
+ *   record carries the refusal, which names who holds the item.
+ * - Heartbeat. While the steps run, the lease is renewed every third of its
+ *   time to live, keeping its fencing token. A renewal the lease refuses (it
+ *   ran out and someone else claimed it, or it was released) means the lease
+ *   is lost: the in-flight step's abort signal fires, no further step starts,
+ *   and the run fails with `lease-lost`. A renewal that fails for any other
+ *   reason (the remote didn't answer) is retried at the next beat; if that
+ *   goes on past the expiry, the next renewal is refused and the lease is lost
+ *   then. These are the semantics of chud's dispatcher
+ *   (packages/runtime/src/dispatch.mjs), which this replaces.
+ * - Fence. Before the run's record is written, one last renewal checks that
+ *   the lease is still this run's, with the same token. Refused, the run is
+ *   recorded as failed with `lease-lost`, never as done.
+ * - Release. When the run ends, the lease is given back with the run's
+ *   outcome (`done`, `not_done`, `gated`, or the Op's own `outcome`), which
+ *   lands on `_leases/<id>.jsonl`. A lost lease is not released: it isn't
+ *   this run's to give back.
+ *
+ * Steps read the lease through {@link workLeaseOutput}: its item, holder,
+ * token and expiry, and for an Op that changes the checkout, the worktree and
+ * branch it works in. An activity that writes somewhere a token can fence
+ * (another ledger, a remote) passes the token along.
+ *
+ * ## Changing the checkout
+ *
+ * An Op with `changesCheckout` (applying a build, `chant workspace upgrade`)
+ * must declare `workLease`, and its leased steps get a git worktree of their
+ * own: `chant/work/<item>` checked out under the repository's git directory,
+ * from the checkout's HEAD, or from the branch as an earlier run left it. The
+ * worktree is removed when the run ends and the branch keeps whatever the
+ * steps committed, for the runner to deliver. The checkout a coding agent is
+ * editing, its index and its uncommitted files, are never touched.
+ */
+import { type StepOutputRef } from "./step-output-ref.js";
+import { type OpConfig } from "./types.js";
+export { WORK_LEASE_STEP_ID } from "./types.js";
+export { workLeaseProblems, workLeaseNeedsRunItem } from "./work-lease-decl.js";
+/** Why a run under a work lease failed when the lease was lost: chud's reason, kept. */
+export declare const LEASE_LOST = "lease-lost";
+/** The branch prefix an Op that changes the checkout works on. */
+export declare const WORK_BRANCH_PREFIX = "chant/work/";
+/** What a run's steps read about its work lease, via {@link workLeaseOutput}. */
+export interface WorkLeaseOutput {
+    item: string;
+    holder: string;
+    /** The fencing token: the same for the whole run unless the lease is lost. */
+    token: string;
+    acquiredAt: string;
+    expiresAt: string;
+    /** The lease ref. */
+    ref: string;
+    /** For an Op that changes the checkout: the worktree its steps work in. Otherwise null. */
+    worktree: string | null;
+    /** For an Op that changes the checkout: the worktree's branch. Otherwise null. */
+    branch: string | null;
+}
+/** How a run's work lease ended, on `OpRunResult.workLease`. */
+export interface WorkLeaseRunResult {
+    /** The item claimed, or null when the run claimed nothing. */
+    item: string | null;
+    holder: string;
+    token: string | null;
+    /** The branch an Op that changes the checkout worked on, or null. */
+    branch: string | null;
+    /** Whether the lease was given back. False when it was lost, or never claimed. */
+    released: boolean;
+    /** The outcome the release recorded, or null when there was no release. */
+    outcome: string | null;
+    /** Why the lease was lost, or null when it wasn't. */
+    lost: string | null;
+    /** Why nothing was claimed, or null when something was. */
+    refusal: string | null;
+}
+/**
+ * A reference to the run's work lease, for a step's args:
+ * `workLeaseOutput("token")`, `workLeaseOutput("worktree")`, or the whole
+ * {@link WorkLeaseOutput} with no path.
+ */
+export declare function workLeaseOutput(path?: keyof WorkLeaseOutput): StepOutputRef;
+/**
+ * The holder a steward's turn claims work leases as:
+ * `<steward>/<op>@<process>`. `chant workspace status --json` reads it back
+ * to show the lease a steward's current turn holds beside its Ops.
+ */
+export declare function stewardWorkHolder(steward: string, op: string, process?: string): string;
+/** What a claim attempt came to, for the executor to record. */
+export type WorkClaimOutcome = {
+    kind: "claimed";
+    lease: WorkLeaseOutput;
+    tried: string[];
+}
+/** Nothing to claim, or every candidate is held. `refusal` says which. */
+ | {
+    kind: "unclaimed";
+    refusal: string;
+    tried: string[];
+};
+export interface RunWorkLeaseOptions {
+    /** The project directory: where the run's ledger is, and what `workLease.kind` is relative to. */
+    cwd: string;
+    holder?: string;
+    /** The item the run names (`--work`), which takes the place of the Op's own. */
+    item?: string;
+    /** Called with a renewal's error that didn't lose the lease, which the next beat retries. */
+    onRenewError?: (message: string) => void;
+}
+/** One run's hold on one work item's lease. Created by the executor for an Op with `workLease`. */
+export declare class RunWorkLease {
+    private readonly config;
+    private readonly opts;
+    readonly holder: string;
+    readonly ttlMs: number;
+    /** Aborts when the lease is lost, so the step in flight stops. */
+    readonly lostSignal: AbortSignal;
+    /** Set once the claim was made or given up on. */
+    attempted: boolean;
+    lease: WorkLeaseOutput | undefined;
+    refusal: string | undefined;
+    lost: string | undefined;
+    private readonly spec;
+    private readonly abort;
+    private timer;
+    private beat;
+    constructor(config: Pick<OpConfig, "name" | "workLease" | "changesCheckout">, opts: RunWorkLeaseOptions);
+    /** The directory whose ledger holds the lease: the kind file's, or the project's. */
+    private get ledgerCwd();
+    /** Whether the claim is due at a step boundary, given the results so far. */
+    due(resultsById: ReadonlyMap<string, unknown>): boolean;
+    /** The candidate ids, in order. Empty when the reference resolved to nothing. */
+    private candidates;
+    /**
+     * Claim the first candidate nobody holds. On a claim, the heartbeat starts,
+     * and for an Op that changes the checkout its worktree is made. Throws when
+     * the claim could not be made for a reason other than someone holding it
+     * (git failed): the run fails, as for any failing step.
+     */
+    claim(resultsById: ReadonlyMap<string, unknown>): Promise<WorkClaimOutcome>;
+    /**
+     * A worktree for `id` on `chant/work/[<member>/]<id>`, under the git
+     * directory so the checkout's own `git status` never lists it. Starts from
+     * the branch when an earlier run left it, from HEAD otherwise.
+     */
+    private makeWorktree;
+    private lose;
+    /** One renewal. Refused, the lease is lost; failed otherwise, the next beat retries. */
+    private renew;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /**
+     * The last renewal before the run's record is written, after the heartbeat
+     * stops. Returns whether the lease is still this run's.
+     */
+    fence(): Promise<boolean>;
+    /**
+     * End the run's hold: stop the heartbeat, remove the worktree (the branch
+     * keeps what was committed), and give the lease back with the outcome
+     * unless it was lost.
+     */
+    finish(status: "ok" | "fail" | "gated" | "waiting", resultsById: ReadonlyMap<string, unknown>): Promise<WorkLeaseRunResult>;
+}
+//# sourceMappingURL=work-lease-run.d.ts.map