toolroll 0.9.6 → 0.9.8

package/dist/store.d.ts

@@ -1,3 +1,4 @@
+import { type Actor } from "./actor.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
 import { type ExecutionProfile, type ChainEntry, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RiskLevel, type RouteOverride } from "./phase-routing.js";
@@ -14,11 +15,21 @@ import { type ProjectAccess } from "./project-access.js";
 import { type LedgerEntry } from "./action-ledger.js";
 import type { LimitReading, LimitWindow } from "./provider-limits.js";
 import { underCeiling, type OrgPolicy, type SavedPolicy } from "./policy.js";
+import { type ReviewSwitch } from "./review-switch.js";
 import { type Billing, type Budget, type BudgetAgent, type BudgetHold, type BudgetScope, type BudgetState, type SpendItem } from "./spend.js";
 import { type RetentionKind, type RetentionPeriods } from "./retention.js";
 import { type CheckoutCleanup } from "./storage.js";
 import { type LedgerChainReport } from "./ledger-chain.js";
 import { type ApprovalGate, type ApprovalRules, type ApproverKind, type Filer } from "./approval-policy.js";
+export type TaskAct = "filed" | "approved" | "cancelled" | "completed" | "asked";
+export type TaskActRow = {
+    act: TaskAct;
+    account: string;
+    lead: boolean;
+    person: string | null;
+    why: string | null;
+    at: string;
+};
 /** Settings → Integrations (no version bump): each integration's last check. `outcome` is ok, failed, or absent (the check found
  * nothing set up, such as no `gh` sign-in). `ok_at` and `error`/`error_at` keep the last success and the last
  * failure across checks, so a row can say both. `account` is a display name only, never a credential. */
@@ -676,6 +687,8 @@ export type FlowScriptRow = {
     savedAt: string;
     language: "shell" | "python" | "node";
     file: string | null;
+    /** Why it can't run yet ("imported": it came in with a flow file and waits for a person's approval); null when it runs. */
+    held: string | null;
 };
 /** Where a card came from when a trigger made it: what to call it and where to look (a GitHub issue, a Linear issue, another flow's card). */
 /** Where a card came from. `mail` (v89): the email it came from, so a reply to its sender stays in the thread.
@@ -1843,9 +1856,9 @@ export declare class Store {
     } | {
         kind: "machine";
         code: "mirror-latched" | "disowned-completion";
-    }, now: Date, admittedFrom: readonly TaskState[] | null): CancellationTransition;
+    }, now: Date, admittedFrom: readonly TaskState[] | null, replacedBy?: string): CancellationTransition;
     private applyCancellationLocked;
-    setTaskState(id: string, state: TaskState, now: Date, mutation?: Mutation, cancellationReason?: string): {
+    setTaskState(id: string, state: TaskState, now: Date, mutation?: Mutation, cancellationReason?: string, replacedBy?: string): {
         ok: true;
     } | {
         ok: false;
@@ -2407,6 +2420,14 @@ export declare class Store {
     };
     /** v99: a policy change, as the ledger keeps it: what changed and from what to what. Nothing is kept when nothing changed. */
     private recordPolicy;
+    /** The project's automatic review switch: its explicit setting, else on
+     * while a hands-off mode is active on it, else off. */
+    reviewSwitch(repo: string, now: Date): ReviewSwitch;
+    /** Turn a project's automatic review on or off; the policy log keeps before → after. */
+    setReviewSwitch(repo: string, on: boolean, by: string, now: Date): {
+        before: ReviewSwitch;
+        after: ReviewSwitch;
+    };
     /** A project deleted (project-delete.ts): who, and what it held → how it went. Returns the entry's id. */
     recordProjectDeleted(by: string, repo: string, held: string, how: string, now: Date): number;
     recordAction(entry: Omit<LedgerEntry, "id" | "detail"> & {
@@ -5089,8 +5110,10 @@ export declare class Store {
         hardStop: boolean;
     }, by: string, now: Date): Budget;
     removeBudget(id: number, by: string, now: Date): boolean;
-    /** How long each kind of data is kept; null is forever (every kind, until someone chooses). */
+    /** How long each kind of data is kept; null is forever. A kind nobody chose keeps its default (evidence 28 days, the rest forever). */
     retentionPeriods(): RetentionPeriods;
+    /** The periods someone chose: only kinds with a saved row. */
+    retentionChosen(): Partial<RetentionPeriods>;
     /** Set how long one kind is kept (null: forever); the ledger keeps before → after. */
     setRetentionPeriod(kind: RetentionKind, days: number | null, by: string, now: Date): RetentionPeriods;
     /** Settings → Storage: when a finished task's clean checkout is removed (the default until someone chooses). */
@@ -6446,7 +6469,10 @@ export declare class Store {
         by: string;
         language?: "shell" | "python" | "node";
         file?: string | null;
+        held?: string | null;
     }, now: Date): number;
+    /** A person approves a held script (one an imported flow brought): from now on it runs. False when it wasn't held. */
+    approveFlowScript(repo: string, name: string): boolean;
     removeFlowScript(repo: string, name: string): boolean;
     /** Claim a card's visit to a step zone. False when another pass holds it or it already finished. */
     claimFlowStep(step: {
@@ -6746,7 +6772,8 @@ export declare class Store {
     getMateTurn(id: number): MateTurn | null;
     liveMateTurnFor(approver: string): MateTurn | null;
     mateStepsOf(mateTurn: number): ChatTurn[];
-    /** Remember a project was opened. Upsert keeps added_at; recency always moves. */
+    /** Remember a project was opened. Upsert keeps added_at; recency always moves.
+     * A project added for the first time starts on Quick checks. */
     upsertProject(path: string, name: string, now: Date): void;
     /** Most recently opened first — the opener page's order. */
     listProjects(): {
@@ -7062,6 +7089,30 @@ export declare class Store {
         group: boolean;
     }): number;
     finishUnspawnedProcess(witness: number, now: Date): void;
+    /** The reconcile road for a pid-less witness a crash or a thrown spawn
+     * left behind: once its run has finished, no live child is tracked for it
+     * here, every other witness of the run has exited and none of the run's
+     * process groups is alive, it settles as never started, with a ledger
+     * entry. A sole pid-less witness has no group to prove gone and stays for
+     * `run settle`. Native witnesses keep their OS-only road. */
+    settleUnspawnedWitnesses(now: Date): number;
+    /** `run settle` (an approver's last resort): every witness of a finished
+     * run that cannot be proven either way is recorded settled under the
+     * approver's reason, in the ledger. Refuses while anything of the run is
+     * alive or could be checked only from another host. Never signals. */
+    settleRunWitnessesByApprover(args: {
+        runId: number;
+        by: string;
+        why: string;
+    }, now: Date): {
+        ok: true;
+        witnesses: number[];
+        repeated: boolean;
+    } | {
+        ok: false;
+        reason: "unknown-run" | "still-running" | "alive";
+        detail: string;
+    };
     recordRunProcess(runId: number, pid: number, now: Date, group?: boolean, witness?: number): void;
     /** The native OS object a witnessed spawn ran inside (v53) — recorded
      * with the spawn, before the target can execute. */
@@ -7147,6 +7198,12 @@ export declare class Store {
      * conversations never freeze the runner's queue.
      */
     liveClaimCount(runner: string, now: Date): number;
+    /** The same live claims as liveClaimCount, by the project their task is placed in. */
+    liveClaimCountsByRepo(runner: string, now: Date): Map<string, number>;
+    /** Every builder's live attempts, by project: what `status` shows against each project's limit. */
+    runningBuildsByRepo(now: Date): Map<string, number>;
+    /** A project's build concurrency changed (project-concurrency.ts): the ledger keeps before → after. */
+    recordProjectConcurrency(by: string, repo: string, before: number, after: number, now: Date): void;
     /** Forward only, and only under the live generation. A stale poller moves nothing. */
     /** v98: an update Telegram pushed, kept until the bridge applies it; false when it's already kept or applied. */
     queueTelegramUpdate(botId: string, updateId: number, payload: string, now: Date): boolean;
@@ -7339,6 +7396,55 @@ export declare class Store {
     }[];
     /** Claim one local day's digest for one person: true once, false if it was already considered. */
     claimEveningDigestDay(account: string, day: string): boolean;
+    /** A lead token for one person, shown once. A new one ends their earlier ones; the ledger names it "lead for <owner>". */
+    mintLeadCredential(owner: string, by: string, now: Date): {
+        id: string;
+        token: string;
+    };
+    /** End every live lead token for one person. */
+    revokeLeadCredentials(owner: string, by: string, now: Date): number;
+    /** Whose lead a presented token is: a live token whose owner is still an approver, or null. */
+    leadFor(presented: string): {
+        owner: string;
+        id: string;
+    } | null;
+    /** Record who did this to a task, when someone is acting. The lead's acts are also in the ledger as "lead for <owner>". */
+    noteTaskAct(taskRef: number, act: TaskAct, now: Date, handed?: {
+        person: string;
+        why: string;
+    }, actor?: Actor | null): void;
+    /** Every recorded act on a task, oldest first. */
+    taskActs(taskRef: number): TaskActRow[];
+    /** Whose lead's work this task is: the last to file, approve or hand it on was that person's lead (null: a person's). */
+    leadWorkOf(taskRef: number): string | null;
+    /** The lead hands a task to a person: it becomes theirs, and they get one message saying why. */
+    askPerson(taskId: string, person: string, why: string, now: Date): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: "unknown-task" | "unknown-person" | "unplaced";
+    };
+    /** The task that replaced a cancelled one, or null. */
+    replacementOf(taskId: string): string | null;
+    /** Every replaced task in one read, for lists: task id → its successor. */
+    replacements(): Map<string, string>;
+    /** Mute or unmute one project's pings for one person. The console and digest keep everything. */
+    setProjectMuted(account: string, repo: string, muted: boolean, now: Date): void;
+    mutedProjects(account: string): string[];
+    /** Whose act made this fact, if anyone's. */
+    notificationActor(id: number): Actor | null;
+    /**
+     * Whether this fact may message this person (every chat, phone and browser asks here). Pings follow
+     * responsibility: a security alert always does; nobody is messaged about their own act (or their lead's);
+     * the lead's work messages nobody unless it is handed to a person or fails with nothing left for the lead
+     * to try; and a person's muted project stays quiet. A fact addressed to one person is theirs. The console
+     * and the evening digest keep every fact either way.
+     */
+    pingAllowed(row: Pick<Notification, "id" | "kind" | "recipient" | "project" | "taskRef">, account: string): boolean;
+    /** The lead's work, which messages nobody: unless it is a security alert or a failure with nothing left for the lead. */
+    leadQuiet(row: Pick<Notification, "id" | "kind" | "taskRef">, actor?: Actor | null): boolean;
+    /** A failure with nothing left for the lead to do: its attempts are spent, or the task has failed for good. */
+    private failedForGood;
     /** The card a destination keeps for this task. A task with none joins a card whose first task was filed within
      * a minute of it (up to eight tasks), or starts its own. */
     chatCardFor(destination: string, taskRef: number, filedAt: string, now: Date): ChatCard;
@@ -7487,6 +7593,8 @@ export declare class Store {
 export declare const TELEGRAM_SKIPPED_RECEIPT = "skipped:before-pairing";
 /** v83: a notification for another person, settled for this destination without sending. */
 export declare const TELEGRAM_SKIPPED_ELSEWHERE = "skipped:for-another-person";
+/** A fact this person is not messaged about: the lead's work, their own act, or a project they muted. */
+export declare const TELEGRAM_SKIPPED_QUIET = "skipped:quiet";
 /**
  * Why the store itself holds a Telegram delivery back: authority,
  * provenance, ordering, a switched-off channel, or a wait it imposed. A