toolroll 0.9.92 → 0.9.94

package/dist/contracts/gateway-tools.d.ts

@@ -49,6 +49,19 @@ export declare const GATEWAY_TOOL_INPUTS: {
             search: "search";
         }>>;
     }, z.core.$strict>;
+    readonly get_code_map: z.ZodObject<{
+        repo: z.ZodString;
+        version: z.ZodOptional<z.ZodInt>;
+        view: z.ZodEnum<{
+            area: "area";
+            file: "file";
+            overview: "overview";
+            search: "search";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     readonly get_assignment: z.ZodObject<{
         ref: z.ZodString;
     }, z.core.$strict>;
@@ -157,6 +170,10 @@ export declare const GATEWAY_TOOL_OUTPUTS: {
         asOf: z.ZodString;
         excerpts: z.ZodArray<z.ZodUnknown>;
     }, z.core.$loose>;
+    readonly get_code_map: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+    }, z.core.$loose>;
     readonly get_assignment: z.ZodObject<{
         version: z.ZodLiteral<1>;
         rootId: z.ZodString;

package/dist/contracts/gateway-tools.js

@@ -11,7 +11,7 @@
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
 import { envelopeSchema } from "./cli.js";
-import { catchUpOutput, decisionOutput, decisionsOutput, LISTED_TASK_STATES, queueColumnsOutput, recapOutput, repositoryContextOutput, scopeText, touches } from "./lead-tools.js";
+import { catchUpOutput, CODE_MAP_VIEWS, codeMapOutput, decisionOutput, decisionsOutput, LISTED_TASK_STATES, queueColumnsOutput, recapOutput, repositoryContextOutput, scopeText, touches } from "./lead-tools.js";
 const text = (key) => z.string().max(TEXT_LIMITS[key]);
 const ref = z.string().min(1).max(TEXT_LIMITS.taskRef);
 const projectPath = text("projectPath").min(1);
@@ -30,6 +30,7 @@ export const ASSIGNMENT_INPUTS = {
 };
 export const GATEWAY_TOOL_INPUTS = {
     get_project_context: z.strictObject({ repo: projectPath, query: text("contextQuery").min(1), mode: z.enum(["search", "impact"]).optional() }),
+    get_code_map: z.strictObject({ repo: projectPath, version: z.int().min(1).optional(), view: z.enum(CODE_MAP_VIEWS), id: text("projectPath").optional(), query: text("contextQuery").optional(), cursor: z.string().max(40).optional() }),
     get_assignment: ASSIGNMENT_INPUTS.show,
     list_assignment_updates: ASSIGNMENT_INPUTS.updates,
     claim_assignment: ASSIGNMENT_INPUTS.claim,
@@ -68,6 +69,7 @@ const proposed = z.looseObject({ proposal: int, kind: z.enum(["next", "reserve",
 const assignmentOutput = z.looseObject({ version: z.literal(1), rootId: str, activeTaskId: str, title: str, state: str, detail: str, attention: z.array(str) });
 export const GATEWAY_TOOL_OUTPUTS = {
     get_project_context: repositoryContextOutput,
+    get_code_map: codeMapOutput,
     get_assignment: assignmentOutput,
     list_assignment_updates: z.looseObject({ events: list, nextCursor: int, hasMore: z.boolean() }),
     claim_assignment: assignmentOutput,

package/dist/contracts/lead-tools.d.ts

@@ -30,6 +30,7 @@ export declare const acceptance: z.ZodArray<z.ZodObject<{
         screenshot: "screenshot";
     }>>;
 }, z.core.$strict>>;
+export declare const CODE_MAP_VIEWS: readonly ["overview", "area", "file", "search"];
 /** Task states a list filters by. */
 export declare const LISTED_TASK_STATES: readonly ["queued", "running", "done", "failed", "cancelled"];
 export declare const LEAD_TOOL_INPUTS: {
@@ -48,6 +49,22 @@ export declare const LEAD_TOOL_INPUTS: {
             search: "search";
         }>>;
     }, z.core.$strict>;
+    readonly get_code_map: z.ZodObject<{
+        repo: z.ZodString;
+        version: z.ZodOptional<z.ZodInt>;
+        view: z.ZodEnum<{
+            area: "area";
+            file: "file";
+            overview: "overview";
+            search: "search";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly refresh_code_map: z.ZodObject<{
+        repo: z.ZodString;
+    }, z.core.$strict>;
     readonly get_action_status: z.ZodObject<{
         proposal: z.ZodInt;
     }, z.core.$strict>;
@@ -74,6 +91,7 @@ export declare const LEAD_TOOL_INPUTS: {
         url: z.ZodOptional<z.ZodString>;
         secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         about: z.ZodOptional<z.ZodString>;
+        on: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     readonly propose_task_action: z.ZodObject<{
         task: z.ZodString;
@@ -537,6 +555,10 @@ export declare const LEAD_TOOL_INPUTS: {
         reference: z.ZodOptional<z.ZodString>;
         decision: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
+    readonly get_flaky_tests: z.ZodObject<{
+        repo: z.ZodString;
+        row: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     readonly get_task_conversation: z.ZodObject<{
         task: z.ZodString;
         limit: z.ZodOptional<z.ZodInt>;
@@ -785,6 +807,22 @@ export declare const LEAD_TOOL_READ_INPUTS: {
             search: "search";
         }>>;
     }, z.core.$strict>;
+    readonly get_code_map: z.ZodObject<{
+        repo: z.ZodString;
+        version: z.ZodOptional<z.ZodInt>;
+        view: z.ZodEnum<{
+            area: "area";
+            file: "file";
+            overview: "overview";
+            search: "search";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly refresh_code_map: z.ZodObject<{
+        repo: z.ZodString;
+    }, z.core.$strict>;
     readonly get_action_status: z.ZodObject<{
         proposal: z.ZodInt;
     }, z.core.$strict>;
@@ -811,6 +849,7 @@ export declare const LEAD_TOOL_READ_INPUTS: {
         url: z.ZodOptional<z.ZodString>;
         secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         about: z.ZodOptional<z.ZodString>;
+        on: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     readonly propose_task_action: z.ZodObject<{
         task: z.ZodString;
@@ -1267,6 +1306,10 @@ export declare const LEAD_TOOL_READ_INPUTS: {
         reference: z.ZodOptional<z.ZodString>;
         decision: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
+    readonly get_flaky_tests: z.ZodObject<{
+        repo: z.ZodString;
+        row: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     readonly commit_to: z.ZodObject<{
         what: z.ZodString;
         when: z.ZodEnum<{
@@ -1503,6 +1546,11 @@ export declare const LEAD_TOOL_READ_INPUTS: {
 export type LeadToolInput<N extends LeadToolName> = z.infer<(typeof LEAD_TOOL_READ_INPUTS)[N]>;
 /** How a tool's call names a key it doesn't know: propose_flow suggests the flow vocabulary's own words. */
 export declare const LEAD_TOOL_OPTIONS: Partial<Record<LeadToolName, ContractOptions>>;
+/** One bounded answer from the shared code map reader (code-map-read.ts `MapAnswer`). */
+export declare const codeMapOutput: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    ok: z.ZodBoolean;
+}, z.core.$loose>;
 /** A repository-context read (repository-context.ts `RepositoryContext`). */
 export declare const repositoryContextOutput: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -1609,6 +1657,16 @@ export declare const LEAD_TOOL_OUTPUTS: {
         asOf: z.ZodString;
         excerpts: z.ZodArray<z.ZodUnknown>;
     }, z.core.$loose>;
+    readonly get_code_map: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly refresh_code_map: z.ZodObject<{
+        request: z.ZodEnum<{
+            "already-queued": "already-queued";
+            queued: "queued";
+        }>;
+    }, z.core.$loose>;
     readonly get_action_status: z.ZodObject<{
         proposal: z.ZodNumber;
         operation: z.ZodString;
@@ -1824,6 +1882,9 @@ export declare const LEAD_TOOL_OUTPUTS: {
     readonly get_project_knowledge: z.ZodObject<{
         revision: z.ZodNumber;
     }, z.core.$loose>;
+    readonly get_flaky_tests: z.ZodObject<{
+        notice: z.ZodString;
+    }, z.core.$loose>;
     readonly get_task_conversation: z.ZodObject<{
         task: z.ZodString;
         messages: z.ZodArray<z.ZodObject<{

package/dist/contracts/lead-tools.js

@@ -46,6 +46,7 @@ export const touches = z.array(text("taskTouch")).max(50);
 export const acceptance = z.array(acceptanceCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria);
 /** A note the operator's own words fill (revise feedback, steering, a flow card's note). */
 const note = z.string().max(LIMITS.note, { error: issue => overBy(LIMITS.note, issue.input) }).describe(`At most ${LIMITS.note} characters; longer is refused with its length, not cut.`);
+export const CODE_MAP_VIEWS = ["overview", "area", "file", "search"];
 /** Task states a list filters by. */
 export const LISTED_TASK_STATES = ["queued", "running", "done", "failed", "cancelled"];
 /** The shared actions the lead proposes with propose_action; flows and subagents have their own tools. */
@@ -54,6 +55,8 @@ export const LEAD_TOOL_INPUTS = {
     get_brief: z.strictObject({ repo: repoId.optional() }),
     get_project_activity: z.strictObject({ repo: repoId, offset: offset.optional() }),
     get_project_context: z.strictObject({ repo: repoId, query: text("contextQuery").min(1), mode: z.enum(["search", "impact"]).optional() }),
+    get_code_map: z.strictObject({ repo: repoId, version: id.optional(), view: z.enum(CODE_MAP_VIEWS), id: text("projectPath").optional(), query: text("contextQuery").optional(), cursor: z.string().max(40).optional() }),
+    refresh_code_map: z.strictObject({ repo: repoId }),
     get_action_status: z.strictObject({ proposal: id }),
     get_actions: z.strictObject({}),
     propose_action: z.strictObject({
@@ -61,7 +64,7 @@ export const LEAD_TOOL_INPUTS = {
         sample: text("actionSample").optional(), content: text("actionContent").optional(), instructions: text("flowInstructions").optional(),
         title: text("actionTitle").optional(), id: z.string().optional(), run: id.optional(), note: note.optional(), catalog: text("actionName").optional(),
         name: text("actionName").optional(), command: text("actionCommand").optional(), args: z.array(text("actionCommand")).max(40).optional(),
-        url: text("actionUrl").optional(), secrets: z.array(text("actionSecret")).max(12).optional(), about: text("actionAbout").optional(),
+        url: text("actionUrl").optional(), secrets: z.array(text("actionSecret")).max(12).optional(), about: text("actionAbout").optional(), on: z.boolean().optional(),
     }),
     propose_task_action: z.strictObject({ task: taskRef, operation: enumOf(Object.keys(CHAT_TASK_ACTIONS)), dependency: taskRef.optional(), run: id.optional() }),
     get_controls: z.strictObject({}),
@@ -100,6 +103,7 @@ export const LEAD_TOOL_INPUTS = {
     get_flow_insights: z.strictObject({ repo: repoId.optional(), flow: id.optional(), days: z.int().min(1).max(90).optional(), card: id.optional(), entry: id.optional() }),
     get_skills: z.strictObject({ repo: repoId, version: z.string().regex(/^[a-f0-9]{20}$/).optional(), offset: offset.optional() }),
     get_project_knowledge: z.strictObject({ repo: repoId, reference: text("knowledgeReference").optional(), decision: id.optional() }),
+    get_flaky_tests: z.strictObject({ repo: repoId, row: text("knowledgeReference").optional() }),
     get_task_conversation: z.strictObject({ task: taskRef, limit: z.int().min(1).max(30).optional() }),
     commit_to: z.strictObject({
         what: text("promise").min(3), when: z.enum(["task", "run", "check", "time"]), task: taskRef.optional(), run: id.optional(),
@@ -185,6 +189,8 @@ const rows = (shape) => z.array(z.looseObject(shape));
 const cardDrafted = z.looseObject({ proposal: int, label: str, awaiting: str, executed: z.literal(false) });
 /** A proposal row drafted by one of the queue, hold, scope and answer tools. */
 const proposed = (kind, shape = {}) => z.looseObject({ proposal: int, kind: z.literal(kind), awaiting: str, ...shape });
+/** One bounded answer from the shared code map reader (code-map-read.ts `MapAnswer`). */
+export const codeMapOutput = z.looseObject({ v: z.literal(1), ok: z.boolean() });
 /** A repository-context read (repository-context.ts `RepositoryContext`). */
 export const repositoryContextOutput = z.looseObject({ version: z.literal(1), readOnly: z.boolean(), query: str, mode: z.enum(["search", "impact"]), asOf: str, excerpts: list });
 /** The local catch-up (assignment-brief.ts `AssignmentCatchUp`). */
@@ -201,6 +207,8 @@ export const LEAD_TOOL_OUTPUTS = {
     get_brief: catchUpOutput,
     get_project_activity: z.looseObject({ asOf: str, since: str, days: int, limit: int, truncated: z.boolean(), ready: z.object({ count: int, oldestFinishedAgeMs: nullable(int), dated: int }), completed: z.looseObject({ count: int }), families: list, familiesTotal: int, familiesOffset: int, nextOffset: nullable(int), incompleteHistory: int }),
     get_project_context: repositoryContextOutput,
+    get_code_map: codeMapOutput,
+    refresh_code_map: z.looseObject({ request: z.enum(["queued", "already-queued"]) }),
     get_action_status: z.looseObject({ proposal: int, operation: str, state: str, outcome: z.unknown(), finishedAt: nullable(str) }),
     get_actions: z.looseObject({ actions: rows({ operation: str, label: str, secureReview: z.boolean(), inputs: z.array(str) }), notice: str }),
     propose_action: cardDrafted,
@@ -241,6 +249,7 @@ export const LEAD_TOOL_OUTPUTS = {
         z.looseObject({ skills: list, nextOffset: nullable(int) }),
     ]),
     get_project_knowledge: z.looseObject({ revision: int }),
+    get_flaky_tests: z.looseObject({ notice: z.string() }),
     get_task_conversation: z.looseObject({ task: str, messages: rows({ from: z.enum(["operator", "lead"]), text: str, at: str }), notice: nullable(str) }),
     commit_to: z.looseObject({ commitment: int, condition: str, expires: str, report: str }),
     release_commitment: z.looseObject({ commitment: int, state: z.literal("cancelled") }),

package/dist/contracts/project-knowledge.d.ts

@@ -68,10 +68,12 @@ export declare const knowledgeOmissionSchema: z.ZodObject<{
     title: z.ZodString;
     reason: z.ZodString;
 }, z.core.$strict>;
-export declare const KNOWLEDGE_SELECTION_VERSION = 1;
+/** Version 2 (docs/plans/learning-loops.md, "Versioned snapshots"): a selection says when it was frozen, and its decision
+ * lines their revision. Version 1 stays readable exactly as it was frozen, its fields as they are. */
+export declare const KNOWLEDGE_SELECTION_VERSION = 2;
 /** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
 export declare const knowledgeSelectionSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     revision: z.ZodInt;
     instructions: z.ZodString;
     references: z.ZodArray<z.ZodObject<{
@@ -91,11 +93,39 @@ export declare const knowledgeSelectionSchema: z.ZodObject<{
         id: z.ZodInt;
         claim: z.ZodString;
         decidedAt: z.ZodString;
+        revision: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>>>;
     repository: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    capturedAt: z.ZodString;
 }, z.core.$strict>;
-/** A frozen selection as it is read back. */
+/** A frozen selection as it is read back: the version it was frozen under. */
 export declare const savedKnowledgeSelectionSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    revision: z.ZodInt;
+    instructions: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        sourceSha: z.ZodNullable<z.ZodString>;
+        sourceRevision: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    omitted: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodInt;
+        claim: z.ZodString;
+        decidedAt: z.ZodString;
+        revision: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>>;
+    repository: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    capturedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const savedKnowledgeSelectionV1Schema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     revision: z.ZodInt;
     instructions: z.ZodString;
@@ -116,11 +146,14 @@ export declare const savedKnowledgeSelectionSchema: z.ZodObject<{
         id: z.ZodInt;
         claim: z.ZodString;
         decidedAt: z.ZodString;
+        revision: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>>>;
     repository: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
 }, z.core.$strict>;
-export type KnowledgeSelection = Omit<z.infer<typeof knowledgeSelectionSchema>, "repository"> & {
+export type KnowledgeSelection = Omit<z.infer<typeof knowledgeSelectionSchema>, "repository" | "version" | "capturedAt"> & {
+    version: 1 | 2;
+    capturedAt?: string;
     repository?: RepositoryContext;
 };
-/** Read a frozen selection: version 1 (every selection ever frozen) as itself, a newer one refused plainly. */
+/** Read a frozen selection: version 1 and 2 each as themselves, a newer one refused plainly. */
 export declare function readKnowledgeSelection(input: unknown): ContractResult<KnowledgeSelection>;

package/dist/contracts/project-knowledge.js

@@ -82,12 +82,18 @@ const selectionShape = (text) => ({
     /** Source excerpts from the crew's checkout (repository-context.ts owns their shape); absent when not captured. */
     repository: z.looseObject({}).optional(),
 });
-export const KNOWLEDGE_SELECTION_VERSION = 1;
+/** Version 2 (docs/plans/learning-loops.md, "Versioned snapshots"): a selection says when it was frozen, and its decision
+ * lines their revision. Version 1 stays readable exactly as it was frozen, its fields as they are. */
+export const KNOWLEDGE_SELECTION_VERSION = 2;
 /** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
-export const knowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(written));
-/** A frozen selection as it is read back. */
-export const savedKnowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(saved));
-/** Read a frozen selection: version 1 (every selection ever frozen) as itself, a newer one refused plainly. */
+export const knowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, { ...selectionShape(written), capturedAt: z.string() });
+/** A frozen selection as it is read back: the version it was frozen under. */
+export const savedKnowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, { ...selectionShape(saved), capturedAt: z.string() });
+export const savedKnowledgeSelectionV1Schema = versioned(1, selectionShape(saved));
+/** Read a frozen selection: version 1 and 2 each as themselves, a newer one refused plainly. */
 export function readKnowledgeSelection(input) {
+    const version = input !== null && typeof input === "object" ? input.version : undefined;
+    if (version === 1)
+        return readVersioned(savedKnowledgeSelectionV1Schema, input);
     return readVersioned(savedKnowledgeSelectionSchema, input);
 }

package/dist/contracts/project-memory.d.ts

@@ -75,11 +75,13 @@ export declare const decisionDraftSchema: z.ZodObject<{
     supersedes: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
 }, z.core.$strict>;
 export type DecisionDraft = z.infer<typeof decisionDraftSchema>;
-/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
+/** One decision in a brief: its id, the choice and when (the revision on snapshots from version 2 on); the why loads on
+ * demand by id. */
 export declare const decisionLineSchema: z.ZodObject<{
     id: z.ZodInt;
     claim: z.ZodString;
     decidedAt: z.ZodString;
+    revision: z.ZodOptional<z.ZodInt>;
 }, z.core.$strict>;
 export type DecisionLine = z.infer<typeof decisionLineSchema>;
 export declare const DECISION_CHANGE_VERSION = 1;

package/dist/contracts/project-memory.js

@@ -38,8 +38,9 @@ export const decisionDraftSchema = z.strictObject({
     sourceRef: z.string().nullable().optional(),
     supersedes: z.int().nullable().optional(),
 });
-/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
-export const decisionLineSchema = z.strictObject({ id: z.int(), claim: z.string(), decidedAt: z.string() });
+/** One decision in a brief: its id, the choice and when (the revision on snapshots from version 2 on); the why loads on
+ * demand by id. */
+export const decisionLineSchema = z.strictObject({ id: z.int(), claim: z.string(), decidedAt: z.string(), revision: z.int().min(1).optional() });
 export const DECISION_CHANGE_VERSION = 1;
 /**
  * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status

package/dist/contracts/release-check.d.ts

@@ -233,7 +233,9 @@ export declare const obligationSnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ObligationSnapshot = z.infer<typeof obligationSnapshotSchema>;
-/** What the plane writes on the check's stdin before closing it. */
+/** What the plane writes on the check's stdin before closing it. `learn` (docs/plans/learning-loops.md) is advisory and
+ * apart from everything else: exact case identities the check is asked to say it ran, on their own line
+ * (LEARN_PREFIX), never in the report and never part of what the check owes. */
 export type CheckHandshake = {
     nonce: string;
     mode: "full" | "targeted";
@@ -241,7 +243,29 @@ export type CheckHandshake = {
     watch: string[];
     owed?: CheckPart[];
     ciSubstitute?: boolean;
+    learn?: string[];
 };
+/** The advisory learning line a check prints before its report: `TOOLROLL-LEARN <json>`, at most 64 KiB, holding only
+ * the requested identities that ran. Never part of the report: buildReport, reportLine and fullCheckProblem don't read
+ * it, and a missing, malformed or oversized one loses learning evidence only. */
+export declare const LEARN_PREFIX = "TOOLROLL-LEARN ";
+export declare const LEARN_MAX_BYTES: number;
+export declare const LEARN_MAX_IDENTITIES = 200;
+export declare const isExactCase: (identity: unknown) => identity is string;
+/** What the plane asks a check to report for learning: exact cases only, first seen first, at most 200. */
+export declare function learnRequest(identities: readonly unknown[]): string[];
+export declare const learnLineSchema: z.ZodObject<{
+    nonce: z.ZodString;
+    results: z.ZodArray<z.ZodObject<{
+        identity: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+            skipped: "skipped";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LearnLine = z.infer<typeof learnLineSchema>;
 /** A unit test: its file and full name. */
 export declare const unitIdentity: (file: string, testName: string) => string;
 /** A unit file. */

package/dist/contracts/release-check.js

@@ -146,6 +146,25 @@ export const obligationSnapshotSchema = versioned(1, {
     base: z.int().min(1),
     earlier: z.array(z.strictObject({ run: z.int().min(1), reportDigest: z.string().max(64).nullable(), failed: z.array(z.string().min(1).max(2600)).max(5000) })).max(200),
 });
+// ------------------------------------------------------------------ advisory learning lines (docs/plans/learning-loops.md)
+/** The advisory learning line a check prints before its report: `TOOLROLL-LEARN <json>`, at most 64 KiB, holding only
+ * the requested identities that ran. Never part of the report: buildReport, reportLine and fullCheckProblem don't read
+ * it, and a missing, malformed or oversized one loses learning evidence only. */
+export const LEARN_PREFIX = "TOOLROLL-LEARN ";
+export const LEARN_MAX_BYTES = 64 * 1024;
+export const LEARN_MAX_IDENTITIES = 200;
+/** An exact case: a unit test (`unit:<file>::<name>`) or a journey (`journey:<script>:<kind>:<group>::<name>`), never a
+ * file, group, part or version; one line, no control characters, at most 2600 characters. */
+const EXACT_CASE = /^(?:unit:[^\u0000-\u001f\\:][^\u0000-\u001f\\]*?::[^\u0000-\u001f]+|journey:(?:app|flows):(?:scripted|real):[A-Za-z0-9._/-]{1,200}::[^\u0000-\u001f]+)$/;
+export const isExactCase = (identity) => typeof identity === "string" && identity.length <= 2600 && EXACT_CASE.test(identity);
+/** What the plane asks a check to report for learning: exact cases only, first seen first, at most 200. */
+export function learnRequest(identities) {
+    return [...new Set(identities.filter(isExactCase))].slice(0, LEARN_MAX_IDENTITIES);
+}
+export const learnLineSchema = z.strictObject({
+    nonce: hex64,
+    results: z.array(z.strictObject({ identity: z.string().min(1).max(2600), state: z.enum(["passed", "failed", "skipped"]) })).max(LEARN_MAX_IDENTITIES),
+});
 // ------------------------------------------------------------------ identities
 /** A unit test: its file and full name. */
 export const unitIdentity = (file, testName) => `unit:${file}::${testName}`;

package/dist/contracts/storage.d.ts

@@ -11,6 +11,13 @@ export declare const checkoutCleanupSchema: z.ZodEnum<{
     finished: "finished";
     never: "never";
 }>;
+/** How long a task stays idle before its clean folder goes (v151, checkout-cleanup.ts). A saved row's NULL is the default. */
+export declare const checkoutIdleSchema: z.ZodEnum<{
+    "14d": "14d";
+    "30d": "30d";
+    "7d": "7d";
+    never: "never";
+}>;
 /** A saved `checkout_cleanup_setting` row (at most one; none means the default), unknown columns ignored. */
 export declare const checkoutCleanupRowSchema: z.ZodObject<{
     cleanup: z.ZodEnum<{
@@ -19,5 +26,12 @@ export declare const checkoutCleanupRowSchema: z.ZodObject<{
         finished: "finished";
         never: "never";
     }>;
+    idle: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        "14d": "14d";
+        "30d": "30d";
+        "7d": "7d";
+        never: "never";
+    }>>>;
 }, z.core.$strip>;
 export type CheckoutCleanup = z.infer<typeof checkoutCleanupSchema>;
+export type CheckoutIdle = z.infer<typeof checkoutIdleSchema>;

package/dist/contracts/storage.js

@@ -6,5 +6,7 @@
  */
 import { z } from "zod";
 export const checkoutCleanupSchema = z.enum(["finished", "2d", "7d", "never"]);
+/** How long a task stays idle before its clean folder goes (v151, checkout-cleanup.ts). A saved row's NULL is the default. */
+export const checkoutIdleSchema = z.enum(["7d", "14d", "30d", "never"]);
 /** A saved `checkout_cleanup_setting` row (at most one; none means the default), unknown columns ignored. */
-export const checkoutCleanupRowSchema = z.object({ cleanup: checkoutCleanupSchema });
+export const checkoutCleanupRowSchema = z.object({ cleanup: checkoutCleanupSchema, idle: checkoutIdleSchema.nullable().optional() });

package/dist/contracts/store-json.d.ts

@@ -166,6 +166,8 @@ declare const STORE_COLUMN_VALUES: {
     readonly "lead_proposal.payload_json": z.ZodUnion<readonly [z.ZodObject<{
         version: z.ZodLiteral<1>;
         operation: z.ZodEnum<{
+            code_map_holdout_end: "code_map_holdout_end";
+            code_map_switch: "code_map_switch";
             decision_record: "decision_record";
             decision_retire: "decision_retire";
             flow_browser: "flow_browser";

package/dist/contracts/youiyoux-request.d.ts

@@ -15,7 +15,7 @@ export declare const YOUIYOUX_FILED_VIA = "youiyoux";
  * Approve all and each one's own Approve and Open. */
 export declare const YOUIYOUX_CARD_KIND = "youiyoux-requests";
 /** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
-export declare const YOUIYOUX_HOME_PATH = "/work?view=needs-you";
+export declare const YOUIYOUX_HOME_PATH = "/tasks?view=needs-you";
 export declare const YOUIYOUX_EVIDENCE: readonly ["screenshot", "check", "changed-path", "manual-review"];
 /** What an options request offers its agent: the one file to write (`.youi/proposals/<proposal>.json`), the props an
  * option may set (enum values from `values`), and whether it may give the component new text. */

package/dist/contracts/youiyoux-request.js

@@ -15,7 +15,7 @@ export const YOUIYOUX_FILED_VIA = "youiyoux";
  * Approve all and each one's own Approve and Open. */
 export const YOUIYOUX_CARD_KIND = "youiyoux-requests";
 /** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
-export const YOUIYOUX_HOME_PATH = "/work?view=needs-you";
+export const YOUIYOUX_HOME_PATH = "/tasks?view=needs-you";
 const text = (max) => z.string().min(1).max(max);
 const who = z.object({ kind: z.enum(["person", "agent"]), name: text(100) });
 // The published schema's date-time: an ISO timestamp with a zone.

package/dist/desktop-access.js

@@ -2,8 +2,8 @@
 import { mkdtempSync, readFileSync, writeFileSync, unlinkSync, rmdirSync, opendirSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
 import { run } from "./exec.js";
+import { checkoutGitSync, checkoutTop } from "./teardown-git.js";
 export function accessFailure(repo, code) {
     if (code === "EROFS")
         return { repo, state: "permission-needed", message: "This project is on a read-only drive. Choose a writable copy; Privacy Settings cannot make a read-only drive writable." };
@@ -23,7 +23,11 @@ export function probeDesktopProject(repo) {
         const directory = opendirSync(repo);
         directory.readSync();
         directory.closeSync();
-        const common = execFileSync("git", ["-C", repo, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", timeout: 4000, stdio: ["ignore", "pipe", "pipe"] }).trim();
+        // The project's own repository, read through a frozen view: a build's include naming a FIFO can't hang the probe.
+        const top = checkoutTop(repo, 4000);
+        if (top === null)
+            throw Error("Not a readable Git checkout");
+        const common = checkoutGitSync(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"], { timeoutMs: 4000, binding: { repo: top } }).trim();
         scratch = mkdtempSync(join(realpathSync(common), "standing-orders-access-"));
         const file = join(scratch, "check");
         writeFileSync(file, "Toolroll access check\n", { flag: "wx", mode: 0o600 });

package/dist/desktop-update.d.ts

@@ -74,8 +74,8 @@ export declare function desktopUpdateWaitingOf(databaseFile: string, inTheWay: (
 /** The same settling reconcile the background worker runs: a finished run's leftover record of a process that never
  * started settles once the run's process groups are proven gone. A record nothing can prove either way stays. */
 export declare function settleLeftoverRecords(db: DatabaseSync, now: Date): number;
-/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms, and `toolroll run settle` only where it
- * can clear the record (it refuses while anything of the run is alive). */
+/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms. Nobody vouches that a run stopped:
+ * Toolroll proves it itself (stop-proof.ts), and `toolroll run settle` only has it look again now. */
 export declare function plainLingering(fallbackRun: number, problem: string): LingeringRun;
 export declare function previewDesktopUpdate(stateDir: string, installed: string, candidate: string, label: string, hooks?: UpdateHooks): Promise<{
     old: DesktopBundle;

package/dist/desktop-update.js

@@ -193,11 +193,11 @@ export function lingeringWork(db) {
     const lingering = lingeringRun(db);
     return lingering && lingeringWords(lingering);
 }
-export const lingeringWords = (l) => l.action ? `${l.on}. If nothing of it is running, run: ${l.action}` : `${l.on}.`;
+export const lingeringWords = (l) => l.action ? `${l.on}. To have Toolroll check again, run: ${l.action}` : `${l.on}.`;
 /** What an update says when it stops waiting on `l`: what is in the way, the command, and that new work resumed. */
 export const stoppedWaitingWords = (l) => `Stopped waiting after 2 minutes. ${l.on}. ${clearWords(l)} New work resumed; nothing was changed.`;
 /** The next step once an update has stopped on `l`. */
-export const clearWords = (l) => l.action ? `If nothing of it is running, run ${l.action}, then update again.` : "Update again once it has stopped.";
+export const clearWords = (l) => l.action ? `To have Toolroll check again, run ${l.action}, then update again.` : "Update again once it has stopped.";
 export function updateWaitingWords(o) {
     const { app, version, stopped, lingering: l } = o;
     const update = `${app ? "App update" : "Update"} to ${version}`;
@@ -206,7 +206,7 @@ export function updateWaitingWords(o) {
         const words = `${update} is waiting for ${on}. New work is paused.`;
         return { app, version, stopped: false, run: null, on, action: null, words, short: words };
     }
-    const next = l.action ? ` If nothing of it is running, run ${l.action}${stopped ? ", then update again" : ""}.` : stopped ? " Update again once it has stopped." : "";
+    const next = l.action ? ` To have Toolroll check again, run ${l.action}${stopped ? ", then update again" : ""}.` : stopped ? " Update again once it has stopped." : "";
     return { app, version, stopped, run: l.run, on: l.on, action: l.action,
         words: `${update} ${stopped ? "stopped waiting" : "is waiting"}: ${l.on}.${next}`,
         short: `${update} ${stopped ? `stopped: run #${l.run} is in the way` : `is waiting on run #${l.run}`}.${next}` };
@@ -284,18 +284,22 @@ export function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirn
 export function settleLeftoverRecords(db, now) {
     return new Store(db).settleUnspawnedWitnesses(now);
 }
-/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms, and `toolroll run settle` only where it
- * can clear the record (it refuses while anything of the run is alive). */
+/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms. Nobody vouches that a run stopped:
+ * Toolroll proves it itself (stop-proof.ts), and `toolroll run settle` only has it look again now. */
 export function plainLingering(fallbackRun, problem) {
     const run = Number(/run #(\d+)/.exec(problem)?.[1] ?? fallbackRun);
-    const settle = `toolroll run settle ${run} --why "it is not running"`;
+    const settle = `toolroll run settle ${run}`;
     const pid = /process (\d+)/.exec(problem)?.[1];
     if (/incomplete spawn witness|before its process witness was recorded/.test(problem))
-        return { run, on: `Run #${run} finished, but Toolroll has no process ID for one of its processes, so it can't confirm that process ended`, action: settle };
-    if (/belongs to another host|another host/.test(problem))
+        return { run, on: `Run #${run} finished, and Toolroll is making sure none of its processes is still running`, action: settle };
+    if (/belongs to another host|another host|another computer/.test(problem))
         return { run, on: `Run #${run} finished on another computer, and Toolroll can only confirm its processes ended there`, action: `${settle} (on that computer)` };
+    if (/can't be proven stopped: .* is using its folder/.test(problem))
+        return { run, on: `Run #${run} finished, but something Toolroll didn't start is using its folder`, action: settle };
+    if (/can't be checked on this computer/.test(problem))
+        return { run, on: `Run #${run} finished, but Toolroll can't check this computer's processes`, action: settle };
     if (/incomplete native containment custody|cannot be proven empty/.test(problem))
-        return { run, on: `Run #${run} finished, but Toolroll can't confirm its sandbox is empty`, action: settle };
+        return { run, on: `Run #${run} finished, but Toolroll can't confirm its sandbox is empty`, action: null };
     if (/still has members/.test(problem))
         return { run, on: `Run #${run} finished, but processes are still running in its sandbox`, action: null };
     if (/workspace is still held/.test(problem))