@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/sessions/compactionCheckpoint.d.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type TodoItem } from "./contracts.js";
+export declare const COMPACTION_CHECKPOINT_EXTENSION = "compaction-checkpoint";
+export interface CompactionCheckpointOptions {
+    /** A stopped run's persisted todo, when the active run is a continuation. */
+    initialTodo?: readonly TodoItem[];
+    /** The current dynamic plan instructions, if this request is in plan mode. */
+    planInstructions?: () => string | null;
+}
+/** Adds only the active run's explicit state to requests made after a compaction. */
+export declare function compactionCheckpoint(options?: CompactionCheckpointOptions): (pi: ExtensionAPI) => void;

package/dist/sdk/sessions/compactionCheckpoint.js

@@ -0,0 +1,79 @@
+import { renderCompactionCheckpoint } from "../prompt/compile.js";
+import { TODO_WRITE } from "../tools/todo.js";
+import { todoItemSchema, MAX_TODO_ITEMS } from "./contracts.js";
+export const COMPACTION_CHECKPOINT_EXTENSION = 'compaction-checkpoint';
+function validatedTodo(value) {
+    if (!Array.isArray(value) || value.length > MAX_TODO_ITEMS)
+        return null;
+    const items = [];
+    for (const valueItem of value) {
+        const item = valueItem;
+        const parsed = todoItemSchema.safeParse({
+            text: typeof item?.text === 'string' ? item.text.trim() : item?.text,
+            status: item?.status
+        });
+        if (!parsed.success)
+            return null;
+        items.push(parsed.data);
+    }
+    return items;
+}
+/** Adds only the active run's explicit state to requests made after a compaction. */
+export function compactionCheckpoint(options = {}) {
+    return (pi) => {
+        let goal = '';
+        let todo = validatedTodo(options.initialTodo ?? []) ?? [];
+        let lastCompactionKey = null;
+        let compacted = false;
+        const reset = () => {
+            goal = '';
+            todo = validatedTodo(options.initialTodo ?? []) ?? [];
+            lastCompactionKey = null;
+            compacted = false;
+        };
+        pi.on('before_agent_start', (event) => {
+            if (event.messageType !== 'user')
+                return;
+            goal = event.prompt;
+            todo = validatedTodo(options.initialTodo ?? []) ?? [];
+            lastCompactionKey = null;
+            compacted = false;
+        });
+        pi.on('tool_result', (event) => {
+            if (event.toolName !== TODO_WRITE || event.isError)
+                return;
+            const items = validatedTodo(event.input.items);
+            if (items)
+                todo = items;
+        });
+        pi.on('context', (event) => {
+            const summary = event.messages.findLast((message) => message.role === 'compactionSummary');
+            const compactionKey = summary ? `${summary.timestamp}:${summary.tokensBefore}` : null;
+            const planInstructions = options.planInstructions?.() ?? null;
+            if (compactionKey && compactionKey !== lastCompactionKey) {
+                lastCompactionKey = compactionKey;
+                compacted = true;
+            }
+            else if (!compactionKey) {
+                lastCompactionKey = null;
+                compacted = false;
+            }
+            if (!compacted)
+                return;
+            const content = renderCompactionCheckpoint({ goal, todo, planInstructions });
+            if (!content)
+                return;
+            return {
+                messages: [...event.messages, {
+                        role: 'custom',
+                        customType: COMPACTION_CHECKPOINT_EXTENSION,
+                        content,
+                        display: false,
+                        timestamp: Date.now()
+                    }]
+            };
+        });
+        pi.on('agent_settled', reset);
+        pi.on('session_tree', reset);
+    };
+}

package/dist/sdk/sessions/continuation.d.ts

@@ -1,6 +1,7 @@
 import type { CapabilitySet } from "../capabilities/types.js";
 import type { HostSection } from "../prompt/compile.js";
-import { type ChecklistItem } from "./contracts.js";
+import type { Checkpoint } from "./contracts.js";
+import { type TodoItem } from "./contracts.js";
 import { type PendingDecision } from "./runStore.js";
 export declare const CONTINUATION_SECTION_ID = "continuation";
 /** Right after the plan section, before the variant's own sections. */
@@ -27,7 +28,11 @@ export interface Continuation {
     capabilities: CapabilitySet | null;
     stoppedAt: string | null;
     terminalReason: string | null;
-    checklist: ChecklistItem[];
+    todo: TodoItem[];
+    /** @deprecated Use `todo`; kept for one release so hosts can migrate. */
+    checklist: TodoItem[];
+    /** The last work-slice handoff, when the run wrote one (PROP-0041). */
+    checkpoint: Checkpoint | null;
     pending: PendingDecision[];
     /** The last tool the run started, and whether it finished. */
     lastTool: {

package/dist/sdk/sessions/continuation.js

@@ -2,7 +2,8 @@
 // own (INV-RUN-4); it says whether a run can be continued and, when the application starts a new
 // run with `continueFrom`, tells the model where the earlier one stopped.
 import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
-import { checklistOf, describeChecklist } from "../tools/checklist.js";
+import { todoOf, describeTodo } from "../tools/todo.js";
+import { checkpointOf, describeCheckpoint } from "../tools/checkpoint.js";
 import { isActiveStatus } from "./contracts.js";
 import { findHistory } from "./history.js";
 import { findRun, pendingDecisions, readEvents, recordedSubagents } from "./runStore.js";
@@ -17,7 +18,7 @@ const CONTINUATION_BUDGET = 2000;
 export function continuationOf(root, runId, sessionDir) {
     const record = findRun(root, runId);
     if (!record) {
-        return { runId, sessionId: '', status: 'missing', resumable: false, reason: 'not_found', resume: null, accountId: null, variant: null, capabilities: null, stoppedAt: null, terminalReason: null, checklist: [], pending: [], lastTool: null, unfinishedSubagents: [] };
+        return { runId, sessionId: '', status: 'missing', resumable: false, reason: 'not_found', resume: null, accountId: null, variant: null, capabilities: null, stoppedAt: null, terminalReason: null, todo: [], checklist: [], checkpoint: null, pending: [], lastTool: null, unfinishedSubagents: [] };
     }
     const events = readEvents(root, runId);
     const started = events.filter((event) => event.type === 'tool.started').at(-1);
@@ -45,7 +46,9 @@ export function continuationOf(root, runId, sessionDir) {
         capabilities,
         stoppedAt: record.endedAt,
         terminalReason: record.terminalReason,
-        checklist: checklistOf(events),
+        checklist: todoOf(events),
+        todo: todoOf(events),
+        checkpoint: checkpointOf(events),
         pending: pendingDecisions(events),
         lastTool,
         unfinishedSubagents: recordedSubagents(root, runId).filter((id) => {
@@ -69,12 +72,14 @@ export function continuationBody(continuation) {
     ];
     if (continuation.lastTool)
         lines.push(continuation.lastTool.finished ? `Its last tool call, ${continuation.lastTool.name}, finished.` : `Its last tool call, ${continuation.lastTool.name}, did not finish; its effect is unknown.`);
-    if (continuation.checklist.length)
-        lines.push('', 'Its checklist when it stopped:', describeChecklist(continuation.checklist));
+    if (continuation.checkpoint)
+        lines.push('', 'The handoff it wrote when it stopped:', describeCheckpoint(continuation.checkpoint));
+    if (continuation.todo.length)
+        lines.push('', 'Its todo list when it stopped:', describeTodo(continuation.todo));
     if (continuation.pending.length)
         lines.push('', 'Unanswered when it stopped (ask again if still needed; never assume an answer):', ...continuation.pending.map(describePending));
     if (continuation.unfinishedSubagents.length)
-        lines.push('', `Subagents that did not finish: ${continuation.unfinishedSubagents.join(', ')}. Start them again if their work is still needed.`);
+        lines.push('', `Subagents that did not finish: ${continuation.unfinishedSubagents.join(', ')}. Their conversations are saved: continue one with spawn_subagent { "continue": "<run ID>" } if its work is still needed, instead of starting it again from scratch.`);
     return lines.join('\n');
 }
 /** The dynamic section for a continuation; on a later run, the empty slot withdraws it. */

package/dist/sdk/sessions/contracts.d.ts

@@ -30,7 +30,10 @@ export declare const runEventTypeSchema: z.ZodEnum<{
     "extension.notice": "extension.notice";
     "reaction.added": "reaction.added";
     "agent.message": "agent.message";
+    "todo.updated": "todo.updated";
     "checklist.updated": "checklist.updated";
+    checkpoint: "checkpoint";
+    heartbeat: "heartbeat";
     "artifact.added": "artifact.added";
     "file.changed": "file.changed";
     "usage.updated": "usage.updated";
@@ -65,8 +68,8 @@ export declare const questionOptionSchema: z.ZodObject<{
     sketch: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type QuestionOption = z.infer<typeof questionOptionSchema>;
-/** One line of the run's checklist. The list has no ids: every update replaces all of it. */
-export declare const checklistItemSchema: z.ZodObject<{
+/** One line of the run's todo list. The list has no ids: every update replaces all of it. */
+export declare const todoItemSchema: z.ZodObject<{
     text: z.ZodString;
     status: z.ZodEnum<{
         completed: "completed";
@@ -74,8 +77,75 @@ export declare const checklistItemSchema: z.ZodObject<{
         in_progress: "in_progress";
     }>;
 }, z.core.$strict>;
-export type ChecklistItem = z.infer<typeof checklistItemSchema>;
-export declare const MAX_CHECKLIST_ITEMS = 50;
+export type TodoItem = z.infer<typeof todoItemSchema>;
+export declare const MAX_TODO_ITEMS = 50;
+export declare const MAX_CHECKPOINT_SUMMARY = 1200;
+export declare const MAX_CHECKPOINT_DONE = 20;
+export declare const MAX_CHECKPOINT_EVIDENCE = 5;
+export declare const MAX_CHECKPOINT_FILES = 20;
+export declare const MAX_CHECKPOINT_CHECKS = 8;
+export declare const MAX_CHECKPOINT_DECISIONS = 8;
+/**
+ * The handoff a reply writes when it reaches its work-slice budget. The harness validates and
+ * records it; the next slice is told where this one stopped from it (PROP-0041).
+ */
+export declare const checkpointItemSchema: z.ZodObject<{
+    item: z.ZodString;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const checkpointFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointCheckSchema: z.ZodObject<{
+    command: z.ZodString;
+    ok: z.ZodBoolean;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointDecisionSchema: z.ZodObject<{
+    what: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointReasonSchema: z.ZodEnum<{
+    budget: "budget";
+    stuck: "stuck";
+    "compaction-thrash": "compaction-thrash";
+    requested: "requested";
+}>;
+declare const checkpointPayload: z.ZodObject<{
+    summary: z.ZodString;
+    done: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        item: z.ZodString;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    next: z.ZodDefault<z.ZodString>;
+    blocked: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        ok: z.ZodBoolean;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        what: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>>;
+    slice: z.ZodNumber;
+    reason: z.ZodEnum<{
+        budget: "budget";
+        stuck: "stuck";
+        "compaction-thrash": "compaction-thrash";
+        requested: "requested";
+    }>;
+}, z.core.$strict>;
+export type Checkpoint = z.infer<typeof checkpointPayload>;
+export type CheckpointItem = z.infer<typeof checkpointItemSchema>;
+export type CheckpointFile = z.infer<typeof checkpointFileSchema>;
+export type CheckpointCheck = z.infer<typeof checkpointCheckSchema>;
+export type CheckpointDecision = z.infer<typeof checkpointDecisionSchema>;
 /** Where a cost figure comes from: Pi reported it, or the tokens were priced at list rates. */
 export declare const costSourceSchema: z.ZodEnum<{
     harness: "harness";
@@ -157,9 +227,37 @@ export declare const accountLimitSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     usedPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    remainingPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     resetsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     windowMinutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        window: "window";
+        rate: "rate";
+        credit: "credit";
+        configured: "configured";
+    }>>>;
+    unit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        requests: "requests";
+        percent: "percent";
+        tokens: "tokens";
+        usd: "usd";
+        currency: "currency";
+        count: "count";
+    }>>>;
+    used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    remaining: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        headers: "headers";
+        estimate: "estimate";
+        provider: "provider";
+    }>>>;
+    observedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type AccountLimit = z.infer<typeof accountLimitSchema>;
 /** Payload schema per discriminant. */
@@ -335,6 +433,16 @@ export declare const runEventPayloadSchemas: {
         agentName: z.ZodString;
         text: z.ZodString;
     }, z.core.$strip>;
+    'todo.updated': z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            status: z.ZodEnum<{
+                completed: "completed";
+                pending: "pending";
+                in_progress: "in_progress";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
     'checklist.updated': z.ZodObject<{
         items: z.ZodArray<z.ZodObject<{
             text: z.ZodString;
@@ -345,6 +453,43 @@ export declare const runEventPayloadSchemas: {
             }>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    checkpoint: z.ZodObject<{
+        summary: z.ZodString;
+        done: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            item: z.ZodString;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        next: z.ZodDefault<z.ZodString>;
+        blocked: z.ZodOptional<z.ZodString>;
+        files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            why: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            ok: z.ZodBoolean;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            what: z.ZodString;
+            why: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>>;
+        slice: z.ZodNumber;
+        reason: z.ZodEnum<{
+            budget: "budget";
+            stuck: "stuck";
+            "compaction-thrash": "compaction-thrash";
+            requested: "requested";
+        }>;
+    }, z.core.$strict>;
+    heartbeat: z.ZodObject<{
+        steps: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+        lastTool: z.ZodNullable<z.ZodString>;
+        compactions: z.ZodNumber;
+        slice: z.ZodNumber;
+        maxToolCalls: z.ZodNumber;
+    }, z.core.$strict>;
     'artifact.added': z.ZodObject<{
         artifactId: z.ZodString;
         name: z.ZodString;
@@ -412,9 +557,37 @@ export declare const runEventPayloadSchemas: {
             id: z.ZodString;
             label: z.ZodString;
             usedPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            remainingPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             resetsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             windowMinutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                error: "error";
+                window: "window";
+                rate: "rate";
+                credit: "credit";
+                configured: "configured";
+            }>>>;
+            unit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                requests: "requests";
+                percent: "percent";
+                tokens: "tokens";
+                usd: "usd";
+                currency: "currency";
+                count: "count";
+            }>>>;
+            used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            remaining: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            source: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                error: "error";
+                headers: "headers";
+                estimate: "estimate";
+                provider: "provider";
+            }>>>;
+            observedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
     'status.changed': z.ZodObject<{
@@ -462,7 +635,10 @@ export declare const runEventSchema: z.ZodObject<{
         "extension.notice": "extension.notice";
         "reaction.added": "reaction.added";
         "agent.message": "agent.message";
+        "todo.updated": "todo.updated";
         "checklist.updated": "checklist.updated";
+        checkpoint: "checkpoint";
+        heartbeat: "heartbeat";
         "artifact.added": "artifact.added";
         "file.changed": "file.changed";
         "usage.updated": "usage.updated";
@@ -494,6 +670,8 @@ export interface RunRecord {
     sessionId: string;
     nativeSessionId: string | null;
     workingDirectory: string | null;
+    /** Canonical filesystem root whose writes this run may make by default. */
+    workspaceRoot?: string | null;
     worktreeId: string | null;
     goal: string | null;
     attachmentCount: number;
@@ -515,6 +693,10 @@ export interface RunRecord {
     profile?: string | null;
     /** The short name a parent gave a subagent, shown in the roster (PROP-0030). */
     title?: string | null;
+    /** The model the run used, as `provider/id`: the launch selection, then the one the session opened. */
+    model?: string | null;
+    /** The reasoning effort the run used. */
+    effort?: string | null;
 }
 export declare const runRecordSchema: z.ZodObject<{
     resumedFromRunId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
@@ -529,6 +711,7 @@ export declare const runRecordSchema: z.ZodObject<{
     sessionId: z.ZodString;
     nativeSessionId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     workingDirectory: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    workspaceRoot: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
     worktreeId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     goal: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     attachmentCount: z.ZodDefault<z.ZodNumber>;
@@ -544,8 +727,11 @@ export declare const runRecordSchema: z.ZodObject<{
     variantVersion: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
     profile: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
     title: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    model: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    effort: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
 }, z.core.$strip>;
 /** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
 export declare function upgradeRunRecord(raw: unknown): unknown;
 export declare const ACTIVE_STATUSES: readonly string[];
 export declare function isActiveStatus(status: string): boolean;
+export {};

package/dist/sdk/sessions/contracts.js

@@ -21,7 +21,11 @@ export const runEventTypeSchema = z.enum([
     'extension.notice',
     'reaction.added',
     'agent.message',
+    'todo.updated',
+    // Written before the rename; accepted so stored run logs keep their lists. Never written now.
     'checklist.updated',
+    'checkpoint',
+    'heartbeat',
     'artifact.added',
     'file.changed',
     'usage.updated',
@@ -172,11 +176,54 @@ const extensionNoticePayload = z.object({
     text: z.string(),
     extension: z.string().optional()
 });
-/** One line of the run's checklist. The list has no ids: every update replaces all of it. */
-export const checklistItemSchema = z.object({ text: z.string().min(1).max(500), status: z.enum(['pending', 'in_progress', 'completed']) }).strict();
-export const MAX_CHECKLIST_ITEMS = 50;
-/** The whole checklist as the model last wrote it; the latest event replaces every earlier one. */
-const checklistPayload = z.object({ items: z.array(checklistItemSchema).max(MAX_CHECKLIST_ITEMS) }).strict();
+/** One line of the run's todo list. The list has no ids: every update replaces all of it. */
+export const todoItemSchema = z.object({ text: z.string().min(1).max(500), status: z.enum(['pending', 'in_progress', 'completed']) }).strict();
+export const MAX_TODO_ITEMS = 50;
+/** The whole todo list as the model last wrote it; the latest event replaces every earlier one. */
+const todoPayload = z.object({ items: z.array(todoItemSchema).max(MAX_TODO_ITEMS) }).strict();
+export const MAX_CHECKPOINT_SUMMARY = 1_200;
+export const MAX_CHECKPOINT_DONE = 20;
+export const MAX_CHECKPOINT_EVIDENCE = 5;
+export const MAX_CHECKPOINT_FILES = 20;
+export const MAX_CHECKPOINT_CHECKS = 8;
+export const MAX_CHECKPOINT_DECISIONS = 8;
+/**
+ * The handoff a reply writes when it reaches its work-slice budget. The harness validates and
+ * records it; the next slice is told where this one stopped from it (PROP-0041).
+ */
+export const checkpointItemSchema = z.object({
+    item: z.string().min(1).max(300),
+    evidence: z.array(z.string().min(1).max(300)).max(MAX_CHECKPOINT_EVIDENCE).default([])
+}).strict();
+export const checkpointFileSchema = z.object({ path: z.string().min(1).max(300), why: z.string().max(200).default('') }).strict();
+export const checkpointCheckSchema = z.object({
+    command: z.string().min(1).max(200),
+    ok: z.boolean(),
+    detail: z.string().max(300).optional()
+}).strict();
+export const checkpointDecisionSchema = z.object({ what: z.string().min(1).max(200), why: z.string().max(300).default('') }).strict();
+export const checkpointReasonSchema = z.enum(['budget', 'stuck', 'compaction-thrash', 'requested']);
+const checkpointPayload = z.object({
+    summary: z.string().max(MAX_CHECKPOINT_SUMMARY),
+    done: z.array(checkpointItemSchema).max(MAX_CHECKPOINT_DONE).default([]),
+    next: z.string().max(500).default(''),
+    blocked: z.string().max(500).optional(),
+    files: z.array(checkpointFileSchema).max(MAX_CHECKPOINT_FILES).default([]),
+    checks: z.array(checkpointCheckSchema).max(MAX_CHECKPOINT_CHECKS).default([]),
+    decisions: z.array(checkpointDecisionSchema).max(MAX_CHECKPOINT_DECISIONS).default([]),
+    /** Which slice of the session wrote it, from 1. */
+    slice: z.number().int().positive(),
+    reason: checkpointReasonSchema
+}).strict();
+/** Counters a live reply reports while it works; a person and the watchdog read liveness from it. */
+const heartbeatPayload = z.object({
+    steps: z.number().int().nonnegative(),
+    elapsedMs: z.number().nonnegative(),
+    lastTool: z.string().max(120).nullable(),
+    compactions: z.number().int().nonnegative(),
+    slice: z.number().int().positive(),
+    maxToolCalls: z.number().int().nonnegative()
+}).strict();
 const artifactPayload = z.object({ artifactId: z.string(), name: z.string(), file: z.unknown().optional() });
 const fileChangedPayload = z.object({ path: z.string(), change: z.enum(['added', 'modified', 'deleted']) });
 /** Where a cost figure comes from: Pi reported it, or the tokens were priced at list rates. */
@@ -228,9 +275,19 @@ export const accountLimitSchema = z.object({
     id: z.string(),
     label: z.string(),
     usedPercent: z.number().nullable().optional(),
+    remainingPercent: z.number().nullable().optional(),
     resetsAt: z.string().nullable().optional(),
     windowMinutes: z.number().nullable().optional(),
-    status: z.string().nullable().optional()
+    status: z.string().nullable().optional(),
+    provider: z.string().nullable().optional(),
+    kind: z.enum(['window', 'rate', 'credit', 'configured', 'error']).nullable().optional(),
+    unit: z.enum(['percent', 'requests', 'tokens', 'usd', 'currency', 'count']).nullable().optional(),
+    used: z.number().nullable().optional(),
+    limit: z.number().nullable().optional(),
+    remaining: z.number().nullable().optional(),
+    source: z.enum(['headers', 'provider', 'estimate', 'error']).nullable().optional(),
+    observedAt: z.string().nullable().optional(),
+    detail: z.string().nullable().optional()
 });
 /** Limit snapshots, plan changes, and classified account failures. */
 const accountStatusPayload = z.object({
@@ -264,7 +321,10 @@ export const runEventPayloadSchemas = {
     'extension.notice': extensionNoticePayload,
     'reaction.added': reactionAddedPayload,
     'agent.message': agentMessagePayload,
-    'checklist.updated': checklistPayload,
+    'todo.updated': todoPayload,
+    'checklist.updated': todoPayload,
+    checkpoint: checkpointPayload,
+    heartbeat: heartbeatPayload,
     'artifact.added': artifactPayload,
     'file.changed': fileChangedPayload,
     'usage.updated': usagePayloadSchema,
@@ -306,6 +366,7 @@ export const runRecordSchema = z.object({
     sessionId: z.string(),
     nativeSessionId: text,
     workingDirectory: text,
+    workspaceRoot: text.optional(),
     worktreeId: text,
     goal: text,
     attachmentCount: z.number().int().nonnegative().default(0),
@@ -320,7 +381,9 @@ export const runRecordSchema = z.object({
     variantScope: text.optional(),
     variantVersion: text.optional(),
     profile: text.optional(),
-    title: text.optional()
+    title: text.optional(),
+    model: text.optional(),
+    effort: text.optional()
 });
 /** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
 export function upgradeRunRecord(raw) {

package/dist/sdk/sessions/control.d.ts

@@ -0,0 +1,72 @@
+/** Which saved history a command acts on: one file in the folder, or the newest there. */
+export interface SessionRef {
+    sessionDir: string;
+    sessionFile?: string | null;
+    /** Recorded in a new history's header. Defaults to the source history's own folder. */
+    cwd?: string | null;
+}
+export interface SessionTreeEntry {
+    id: string;
+    parentId: string | null;
+    type: string;
+    /** `user`, `assistant`, `toolResult`, ... for a message entry. */
+    role?: string;
+    /** One line of what the entry says, at most 160 characters. */
+    text: string;
+    label?: string;
+    timestamp: string;
+    /** How deep in the tree, for indentation. */
+    depth: number;
+}
+export interface SessionTree {
+    sessionFile: string;
+    leafId: string | null;
+    entries: SessionTreeEntry[];
+    /** The person's messages on the current branch, newest last: where `/fork` may start. */
+    forkPoints: {
+        entryId: string;
+        text: string;
+    }[];
+}
+/** A move without a summary is saved as this entry, so the next turn opens on the chosen branch. */
+export declare const NAVIGATION_ENTRY = "xingular-navigation";
+export declare function tree(ref: SessionRef): SessionTree;
+/**
+ * Moves the conversation to another entry without a summary. Choosing one of the person's
+ * messages goes to just before it and gives its text back to edit, as the terminal does.
+ */
+export declare function navigate(ref: SessionRef & {
+    entryId: string;
+}): {
+    leafId: string | null;
+    editorText?: string;
+};
+/** A new history in `targetDir` that ends just before one of the person's messages. */
+export declare function fork(ref: SessionRef & {
+    entryId: string;
+    targetDir: string;
+}): {
+    sessionFile: string;
+    editorText: string;
+};
+/** A new history in `targetDir` with the whole current branch. */
+export declare function clone(ref: SessionRef & {
+    targetDir: string;
+}): {
+    sessionFile: string;
+};
+export declare function rename(ref: SessionRef & {
+    name: string;
+}): {
+    name: string;
+};
+/** The text of the last reply on the current branch, or null before the first. */
+export declare function lastReply(ref: SessionRef): {
+    text: string | null;
+};
+/** Writes the current branch as JSONL. HTML needs a live session: see `SessionCommand`. */
+export declare function exportJsonl(ref: SessionRef & {
+    path: string;
+}): {
+    path: string;
+};