@zq-silk/yui 0.15.7 → 0.15.9

package/dist/storage/migrations/submitIntent.js

@@ -0,0 +1,126 @@
+import { createTaskEvent } from "../../event/taskEvent.js";
+/**
+ * Storage 18 -> 19 data step for task-32 Requirement A (submit intent & Draft
+ * auto-routing).
+ *
+ * This helper is INDEPENDENT, deterministic and idempotent. The unified 18 -> 19
+ * migration owned by the artifacts WorkItem REGISTERS it (as its `migrateData`)
+ * and bumps `CURRENT_STORAGE_VERSION`; this module neither registers a second
+ * migration nor changes any schema.
+ *
+ * Requirement A adds three optional fields inside `messages.payload`, all part of
+ * this same 18 -> 19 contract even though each is optional — "optional" governs a
+ * single record's shape, not the Home compatibility line, so the version
+ * transition is still declared here and carried by the unified migration:
+ *
+ *  - `intent` (record | discuss | develop): an absent value already reads as
+ *    `discuss` (never `develop`), so historical Messages need no rewrite.
+ *  - `submissionKey`: the client-chosen idempotency key. Only ever set going
+ *    forward; NO historical key is fabricated (task-32 §2.3, message review), so
+ *    old Messages stay keyless and non-idempotent exactly as before.
+ *  - `submissionReceipt`: the frozen disposition a keyed submission replays from.
+ *    Written only alongside a new `submissionKey`, so it too never appears on
+ *    historical data.
+ *
+ * Because none of the three needs a value backfilled onto old rows, the only data
+ * step this migration performs is the planning-entered reconstruction below.
+ *
+ * The one fact old data cannot express is "this Draft already entered planning".
+ * Before Requirement A a Leader-waking user/operator submission on a Draft WAS
+ * the planning discussion, but it left no `task.planning-entered` fact because
+ * that event type did not exist. After the upgrade `develop` auto-activates an
+ * *unplanned* Draft; without this step a Draft that was mid-discussion would be
+ * mis-read as unplanned and snatched into auto-activation (task-32 §2.2, §4).
+ *
+ * So for every Draft that received at least one legitimate historical planning
+ * submission this appends exactly one `task.planning-entered` event, which makes
+ * {@link draftHasEnteredPlanning} derive `true` and routes a later develop to
+ * manual activation. A qualifying submission is an *unaddressed* user/operator
+ * Message that was not save-only (`wakePolicy !== "none"`) — byte-for-byte the
+ * same shape the new discuss path routes through the shared submission service.
+ *
+ * This is deliberately the conservative direction: it can only ever make develop
+ * MORE cautious, never activate a Draft it should not. Save-only Messages (old
+ * `wakePolicy === "none"`, the shape `record` now names) are excluded, so a Draft
+ * that only ever recorded context stays legitimately unplanned and its first
+ * develop may still auto-activate. Non-Draft Tasks are skipped because
+ * {@link draftHasEnteredPlanning} answers only about Drafts, and Activation
+ * requests are left untouched — a legacy request's absent `origin` is the
+ * truthful marker that it stays behind explicit activation.
+ */
+export function migrateSubmitIntent(db) {
+    const drafts = db.prepare("SELECT task_id FROM tasks_catalog WHERE status = 'draft'").all();
+    if (drafts.length === 0)
+        return;
+    const listMessages = db.prepare("SELECT payload FROM messages WHERE task_id = ? ORDER BY seq ASC");
+    const listEventRows = db.prepare("SELECT event_id, type FROM events WHERE task_id = ?");
+    const readHighWater = db.prepare("SELECT high_water FROM id_sequences WHERE task_id = ? AND kind = 'event'");
+    // Advance the per-Task event high-water to exactly the id we just consumed, so
+    // the runtime keeps allocating strictly above every migrated event (mirrors
+    // sqliteStore's id_sequences bookkeeping).
+    const upsertHighWater = db.prepare(`INSERT INTO id_sequences (task_id, kind, high_water) VALUES (?, 'event', ?)
+     ON CONFLICT(task_id, kind) DO UPDATE SET high_water = ?`);
+    const insertEvent = db.prepare("INSERT INTO events (task_id, event_id, type, occurred_at, payload) VALUES (?, ?, ?, ?, ?)");
+    for (const { task_id: taskId } of drafts) {
+        const eventRows = listEventRows.all(taskId);
+        // Idempotent: a Draft that already carries the fact (from a prior run of this
+        // migration, or from a real runtime planning entry) is left untouched.
+        if (eventRows.some((row) => row.type === PLANNING_ENTERED_EVENT_TYPE))
+            continue;
+        const entry = firstPlanningSubmission(listMessages.all(taskId));
+        if (entry === undefined)
+            continue;
+        // Allocate the next event id from the greater of the recorded high-water and
+        // the largest event id actually present, so a fixture or historical database
+        // whose id_sequences lags the events table can never produce a colliding id.
+        const highWater = readHighWater.get(taskId)?.high_water ?? 0;
+        const maxEventSeq = eventRows.reduce((max, row) => Math.max(max, eventSequence(row.event_id)), 0);
+        const seq = Math.max(highWater, maxEventSeq) + 1;
+        // Build through the shared constructor so a migrated event is byte-identical
+        // in shape to one the shared submission service writes at runtime, and dated
+        // to the historical submission rather than the wall-clock upgrade moment.
+        const event = createTaskEvent(`event-${seq}`, taskId, PLANNING_ENTERED_EVENT_TYPE, { messageId: entry.id, intent: "discuss", derivedBy: MIGRATION_PROVENANCE }, new Date(entry.createdAt));
+        insertEvent.run(taskId, event.id, event.type, event.createdAt, JSON.stringify(event));
+        upsertHighWater.run(taskId, seq, seq);
+    }
+}
+/**
+ * The never-compacted event type recording a Draft entered planning. Inlined as a
+ * literal rather than imported so this released migration stays frozen against a
+ * future runtime rename of the constant; `TASK_PLANNING_ENTERED_EVENT` is the
+ * runtime owner, and a tripwire test asserts the two never diverge.
+ */
+const PLANNING_ENTERED_EVENT_TYPE = "task.planning-entered";
+/** Marks the event as reconstructed by this migration, for later audit. */
+const MIGRATION_PROVENANCE = "submit-intent-migration";
+/**
+ * The earliest Message on a Draft that represents a historical planning
+ * submission, or `undefined` if the Draft only ever recorded save-only context.
+ *
+ * A qualifying Message is an unaddressed (`recipient === undefined`) user or
+ * operator Message whose wake policy was not `none`. An absent wake policy
+ * qualifies: before Requirement A that was the default Leader-waking submission,
+ * exactly the shape an omitted intent normalizes to `discuss` today.
+ */
+function firstPlanningSubmission(rows) {
+    for (const row of rows) {
+        const message = JSON.parse(row.payload);
+        if (message.kind !== "user" && message.kind !== "operator")
+            continue;
+        if (message.recipient !== undefined)
+            continue; // an addressed continuation, not a submission
+        if (message.wakePolicy === "none")
+            continue; // old save-only == record, never planning
+        if (typeof message.id !== "string")
+            continue;
+        if (typeof message.createdAt !== "string")
+            continue;
+        return { id: message.id, createdAt: message.createdAt };
+    }
+    return undefined;
+}
+/** The numeric suffix of an `event-<n>` id, or 0 for any unexpected shape. */
+function eventSequence(eventId) {
+    const match = /^event-(\d+)$/.exec(eventId);
+    return match === null ? 0 : Number.parseInt(match[1], 10);
+}

package/dist/storage/sqliteSchema.js

@@ -21,10 +21,13 @@
  * is a no-op; a crash mid-upgrade rolls the whole migration transaction back.
  */
 import { createHash } from "node:crypto";
+import { REMOVE_RUNTIME_GENERATION_SQL, removeRuntimeGenerationRecords } from "./migrations/removeRuntimeGeneration.js";
+import { migrateAgentRunContract } from "./migrations/agentRunContract.js";
+import { migrateArtifactsToGit } from "./migrations/artifactsToGit.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
 /** Telemetry retention bounds (§4.4). Open question 3 in §11; defaults from the design. */
-export const TELEMETRY_KEEP_PER_GENERATION = 200;
-export const TELEMETRY_TURN_CAP = 50_000;
+export const TELEMETRY_KEEP_PER_RUN = 200;
+export const TELEMETRY_RUN_CAP = 50_000;
 /**
  * Version 1 migration: creates every table and index.
  *
@@ -697,6 +700,449 @@ ON durable_jobs(task_id, json_extract(payload, '$.operation.actorId'),
         // Accepted inputs/results can use an exact attempt without a native Turn id.
         // Preserve all valid historical records; never repair failed Turns or logs.
         sql: "SELECT 1; -- exact attempt identity without a fabricated native Turn id"
+    },
+    {
+        version: 4,
+        name: "session-and-process-identity",
+        introducedIn: "0.15.8",
+        sql: REMOVE_RUNTIME_GENERATION_SQL,
+        migrateData: removeRuntimeGenerationRecords
+    },
+    {
+        version: 5,
+        name: "project-resource-artifacts",
+        introducedIn: "0.15.8",
+        sql: `
+CREATE TABLE artifacts (
+  task_id TEXT NOT NULL REFERENCES tasks_catalog(task_id),
+  id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (task_id, id)
+);
+CREATE TABLE local_resources (
+  id TEXT PRIMARY KEY,
+  canonical_identity TEXT NOT NULL UNIQUE,
+  payload TEXT NOT NULL
+);
+CREATE TABLE environment_preparations (
+  task_id TEXT NOT NULL REFERENCES tasks_catalog(task_id),
+  id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (task_id, id)
+);
+UPDATE projects SET payload = json_set(payload,
+  '$.schemaVersion', 6, '$.resourceRefs', json('[]'),
+  '$.defaultCapabilityProviders', json('{}'));
+`
+    },
+    {
+        version: 6,
+        name: "session-endpoint-implementation",
+        introducedIn: "0.15.8",
+        // Valid earlier Sessions used these two built-in protocols. Generation 1
+        // retains those codecs and identities behind the new execution boundary.
+        // Preserve native IDs, effective snapshots and all historical results.
+        sql: `
+UPDATE role_session_sets SET payload = json_set(payload, '$.sessions', json((
+  SELECT json_group_object(key, json_set(value, '$.schemaVersion', 6,
+    '$.endpointImplementation', json_object(
+      'id', 'yui.agent-endpoint.' || json_extract(value, '$.adapterId'), 'generation', '1')))
+  FROM json_each(payload, '$.sessions')
+)));
+UPDATE role_session_sets SET payload = json_set(payload, '$.history', json((
+  SELECT json_group_array(json_set(value, '$.schemaVersion', 6,
+    '$.endpointImplementation', json_object(
+      'id', 'yui.agent-endpoint.' || json_extract(value, '$.adapterId'), 'generation', '1')))
+  FROM json_each(payload, '$.history')
+))) WHERE json_type(payload, '$.history') = 'array';
+UPDATE global_role_session_sets SET payload = json_set(payload, '$.sessions', json((
+  SELECT json_group_object(key, json_set(value, '$.schemaVersion', 6,
+    '$.endpointImplementation', json_object(
+      'id', 'yui.agent-endpoint.' || json_extract(value, '$.adapterId'), 'generation', '1')))
+  FROM json_each(payload, '$.sessions')
+)));
+UPDATE global_role_session_sets SET payload = json_set(payload, '$.history', json((
+  SELECT json_group_object(key, json_set(value, '$.schemaVersion', 6,
+    '$.endpointImplementation', json_object(
+      'id', 'yui.agent-endpoint.' || json_extract(value, '$.adapterId'), 'generation', '1')))
+  FROM json_each(payload, '$.history')
+))) WHERE json_type(payload, '$.history') = 'object';
+`
+    },
+    {
+        version: 7,
+        name: "task-facts-and-explicit-acceptance",
+        introducedIn: "0.15.8",
+        // Retain the complete retirement metadata/events and diagnostic facts.
+        // Only the public lifecycle changes; ordinary stores read one shape.
+        sql: `
+UPDATE task_records SET payload = json_set(payload, '$.status', 'cancelled')
+WHERE json_extract(payload, '$.status') = 'retired';
+UPDATE task_records SET payload = json_set(payload, '$.retirementIsolation', json('true'))
+WHERE json_extract(payload, '$.retiredAt') IS NOT NULL;
+UPDATE tasks_catalog SET status = 'cancelled' WHERE status = 'retired';
+UPDATE tasks_catalog SET lifecycle = 'cancelled' WHERE lifecycle = 'retired';
+UPDATE task_records SET brief = json_set(brief, '$.revision', 1) WHERE brief IS NOT NULL;
+UPDATE work_items SET payload = json_set(payload,
+  '$.historicalState', json_patch(json('{}'), json_object(
+    'status', json_extract(payload, '$.status'),
+    'outcome', json_extract(payload, '$.outcome'),
+    'endedAt', json_extract(payload, '$.endedAt'))),
+  '$.status', CASE status WHEN 'completed' THEN 'accepted' WHEN 'retired' THEN 'retired' ELSE 'open' END);
+UPDATE work_items SET payload = json_remove(payload, '$.outcome', '$.endedAt')
+WHERE json_extract(payload, '$.status') = 'open';
+UPDATE work_items SET status = json_extract(payload, '$.status');
+UPDATE work_items SET payload = json_set(payload, '$.currentCandidateId',
+  json_extract(payload, '$.candidates[#-1].id'))
+WHERE json_extract(payload, '$.historicalState.status') = 'awaiting_acceptance';
+UPDATE work_items SET payload = json_set(payload, '$.acceptedCandidateId',
+  json_extract(payload, '$.candidates[#-1].id'))
+WHERE status = 'accepted' AND json_array_length(payload, '$.candidates') > 0;
+`
+    },
+    {
+        version: 8,
+        name: "event-owned-edit-history",
+        introducedIn: "0.15.8",
+        // Move embedded histories to one immutable import event per Task.
+        // Existing events stay byte-identical; imports supply otherwise missing
+        // historical fields and are evidence only, never executable lifecycle input.
+        // Candidates may now carry optional fixed Artifact refs; absent refs remain
+        // valid for historical Candidates, so this payload addition needs no backfill.
+        sql: `
+CREATE TEMP TABLE migrated_edit_history AS
+SELECT records.task_id,
+  COALESCE(sequences.high_water, 0) + 1 AS sequence,
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now') AS imported_at,
+  json_object(
+    'sourceStorageVersion', '7',
+    'taskOutcomes', '' || COALESCE(json_extract(records.payload, '$.outcomeHistory'), '[]'),
+    'workAcceptances', '' || COALESCE((
+      SELECT json_group_array(json_object(
+        'workItemId', work_item_id,
+        'history', json_extract(payload, '$.acceptanceHistory')))
+      FROM (SELECT * FROM work_items
+        WHERE task_id = records.task_id
+          AND json_array_length(payload, '$.acceptanceHistory') > 0
+        ORDER BY work_item_id)
+    ), '[]')
+  ) AS history
+FROM task_records AS records
+LEFT JOIN id_sequences AS sequences
+  ON sequences.task_id = records.task_id AND sequences.kind = 'event'
+WHERE json_array_length(records.payload, '$.outcomeHistory') > 0
+  OR EXISTS (SELECT 1 FROM work_items
+    WHERE task_id = records.task_id AND json_array_length(payload, '$.acceptanceHistory') > 0);
+
+INSERT INTO events (task_id, event_id, type, occurred_at, payload)
+SELECT task_id, 'event-' || sequence, 'history.imported', imported_at,
+  json_object('schemaVersion', 2, 'id', 'event-' || sequence,
+    'taskId', task_id, 'type', 'history.imported',
+    'createdAt', imported_at, 'payload', json(history))
+FROM migrated_edit_history;
+INSERT INTO id_sequences (task_id, kind, high_water)
+SELECT task_id, 'event', sequence FROM migrated_edit_history WHERE true
+ON CONFLICT(task_id, kind) DO UPDATE SET high_water = excluded.high_water;
+DROP TABLE migrated_edit_history;
+
+UPDATE task_records SET payload = json_remove(payload, '$.outcomeHistory'),
+  brief = CASE WHEN brief IS NULL THEN NULL ELSE json_remove(brief, '$.revision') END;
+UPDATE work_items SET payload = json_remove(payload, '$.acceptanceHistory');
+`
+    },
+    {
+        version: 9,
+        name: "adopted-agent-execution-environment",
+        introducedIn: "0.15.8",
+        // Optional Role selection and immutable Session/Turn effective snapshot.
+        // Existing records deliberately keep their managed-workspace execution;
+        // adopted preparations must never be inferred as an automatic binding.
+        sql: "SELECT 1; -- explicit adopted execution environment; absent means managed workspace"
+    },
+    {
+        version: 10,
+        name: "plugin-validation-evidence",
+        introducedIn: "0.15.8",
+        sql: `
+CREATE TABLE plugin_validations (
+  task_id TEXT NOT NULL REFERENCES tasks_catalog(task_id),
+  id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (task_id, id)
+);
+`
+    },
+    {
+        version: 11,
+        name: "plugin-enable-intent",
+        introducedIn: "0.15.8",
+        // A v10 validation proves no enable/disable choice. Preserve it unchanged;
+        // never infer desired configuration from historical reports or processes.
+        sql: `
+CREATE TABLE plugin_intents (
+  task_id TEXT NOT NULL REFERENCES tasks_catalog(task_id),
+  plugin_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (task_id, plugin_id)
+);
+`
+    },
+    {
+        // Renumbered from 10 to 12 when this branch adopted upstream master: PR320
+        // took 10 and 11 while this work was in review. Both are already merged, so
+        // they own those numbers; this migration appends after them rather than
+        // competing for a number, and no released entry is touched.
+        version: 12,
+        name: "draft-planning-and-deferred-activation",
+        // Same unreleased release as migrations 4-11: this does not bump the version.
+        introducedIn: "0.15.8",
+        // One current-version migration for everything this change adds. No existing
+        // record is rewritten and no payload is backfilled:
+        //
+        //   - the optional Task activation request: absent means activation was
+        //     never explicitly requested, so a Draft is never inferred to have
+        //     requested it;
+        //   - its bounded settled-request history: absent means no request ever
+        //     reached a terminal disposition on this Task. This is a display
+        //     projection, not the authority: whether an explicitly cancelled or
+        //     adopted requestId may be replayed is decided from the durable
+        //     activation event ledger (never compacted), so eviction from this
+        //     bounded list never resurrects a decided outcome — per-request state
+        //     inside the Task that owns it, not a second scheduling or operation
+        //     ledger;
+        //   - the planning Turn purpose: historical Turns keep their execution or
+        //     review purpose untouched.
+        //
+        // The partial indexes bound Draft planning selection and pending-activation
+        // recovery to the few rows that qualify, so no execution phase scans Task
+        // history to find them. Creating an index adds no row and rewrites no
+        // payload.
+        sql: `
+-- explicit activation request, its bounded settled history, and planning Turn
+-- purpose; absent means activation was never requested
+CREATE INDEX IF NOT EXISTS idx_turns_planning_active ON turns(task_id, turn_id)
+  WHERE status = 'active' AND json_extract(payload, '$.purpose') = 'planning';
+CREATE INDEX IF NOT EXISTS idx_tasks_activation_pending ON task_records(task_id)
+  WHERE json_extract(payload, '$.activationRequest.disposition') = 'pending';
+`
+    },
+    {
+        version: 13,
+        name: "session-authority-and-execution-admission",
+        introducedIn: "0.15.9",
+        sql: "SELECT 1; -- AgentRun contract, notification admission and Session authority",
+        migrateData: migrateAgentRunContract
+    },
+    {
+        version: 14,
+        name: "acp-session-workspace-configuration",
+        introducedIn: "0.15.10",
+        // ACP is a new legal adapter/configuration value, including its optional
+        // additional workspace roots. The v13 baseline has no ACP bindings; existing
+        // Codex/Claude configuration and Session history remain valid unchanged.
+        // This widens the persistent contract without rewriting payloads or earlier
+        // migration checksums. Workspace delivery is negotiated at initialize, not
+        // stored as another configuration authority.
+        sql: "SELECT 1; -- ACP bindings may carry additionalDirectories; history stays valid"
+    },
+    {
+        version: 15,
+        name: "agent-execution-component",
+        introducedIn: "0.15.10",
+        // Which product executes is now its own recorded fact, separate from the
+        // connection plan that reaches it. The plan keeps its `adapterId` name and
+        // its meaning; only the product identity is new.
+        //
+        // The backfill is a total function of the stored plan, never of a command
+        // string. `codex` and `claude` each have exactly one component, so those
+        // rows gain their true value. Every `acp` row becomes `unknown-acp-agent`:
+        // a v14 Home cannot say which product answered, and an executable named
+        // `claude-agent-acp` is not evidence that it was the Claude Agent SDK. The
+        // unidentified value is the honest one and stays correctable by hand.
+        //
+        // Sessions keep their own recorded component, so a Session started before
+        // this migration continues against exactly the implementation it began on.
+        //
+        // Every persisted effective snapshot must be reached, not only the ones on
+        // Session sets: `validateEffectiveLaunchSnapshot` demands schemaVersion 4,
+        // and the upgrade verifier replays it over Runs, WorkItem ExecutionLanes
+        // and ReviewRound ExecutionLanes too. A Home holding any of those would
+        // otherwise fail the upgrade and roll back. The list below is the
+        // verifier's own reachable set, not a scan for fields that look similar.
+        sql: `
+UPDATE configured_agents SET payload = json_set(payload,
+  '$.schemaVersion', 3,
+  '$.component', CASE json_extract(payload, '$.adapterId')
+    WHEN 'codex' THEN 'codex-cli'
+    WHEN 'claude' THEN 'claude-code-cli'
+    ELSE 'unknown-acp-agent' END)
+WHERE json_extract(payload, '$.component') IS NULL;
+
+UPDATE global_roles SET payload = json_set(payload, '$.agentBindings', json((
+  SELECT json_group_object(key, json_set(value, '$.component',
+    CASE json_extract(value, '$.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.agentBindings')
+))) WHERE json_type(payload, '$.agentBindings') = 'object';
+
+UPDATE task_roles SET payload = json_set(payload, '$.agentBindings', json((
+  SELECT json_group_object(key, json_set(value, '$.component',
+    CASE json_extract(value, '$.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.agentBindings')
+))) WHERE json_type(payload, '$.agentBindings') = 'object';
+
+UPDATE global_role_session_sets SET payload = json_set(payload, '$.sessions', json((
+  SELECT json_group_object(key, json_set(value, '$.effective.schemaVersion', 4,
+    '$.effective.component', CASE json_extract(value, '$.effective.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.sessions')
+))) WHERE json_type(payload, '$.sessions') = 'object';
+UPDATE global_role_session_sets SET payload = json_set(payload, '$.history', json((
+  SELECT json_group_object(key, json_set(value, '$.effective.schemaVersion', 4,
+    '$.effective.component', CASE json_extract(value, '$.effective.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.history')
+))) WHERE json_type(payload, '$.history') = 'object';
+
+UPDATE role_session_sets SET payload = json_set(payload, '$.sessions', json((
+  SELECT json_group_object(key, json_set(value, '$.effective.schemaVersion', 4,
+    '$.effective.component', CASE json_extract(value, '$.effective.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.sessions')
+))) WHERE json_type(payload, '$.sessions') = 'object';
+UPDATE role_session_sets SET payload = json_set(payload, '$.history', json((
+  SELECT json_group_array(json_set(value, '$.effective.schemaVersion', 4,
+    '$.effective.component', CASE json_extract(value, '$.effective.adapterId')
+      WHEN 'codex' THEN 'codex-cli'
+      WHEN 'claude' THEN 'claude-code-cli'
+      ELSE 'unknown-acp-agent' END))
+  FROM json_each(payload, '$.history')
+))) WHERE json_type(payload, '$.history') = 'array';
+
+-- A Turn records the launch it actually ran on, one snapshot per row.
+UPDATE turns SET payload = json_set(payload,
+  '$.effective.schemaVersion', 4,
+  '$.effective.component', CASE json_extract(payload, '$.effective.adapterId')
+    WHEN 'codex' THEN 'codex-cli'
+    WHEN 'claude' THEN 'claude-code-cli'
+    ELSE 'unknown-acp-agent' END)
+WHERE json_type(payload, '$.effective') = 'object';
+
+-- ExecutionLane launch facts are frozen per Lane, inside an array of Groups
+-- that each hold an array of Lanes. A Lane that was never dispatched has no
+-- effective at all, and must keep that absence: json_set would otherwise
+-- create a partial snapshot the Lane validator rejects as incomplete.
+UPDATE work_items SET payload = json_set(payload, '$.executionGroups', json((
+  SELECT json_group_array(json_set(grp.value, '$.lanes', json((
+    SELECT json_group_array(CASE
+      WHEN json_type(lane.value, '$.effective') = 'object'
+      THEN json_set(lane.value, '$.effective.schemaVersion', 4,
+        '$.effective.component', CASE json_extract(lane.value, '$.effective.adapterId')
+          WHEN 'codex' THEN 'codex-cli'
+          WHEN 'claude' THEN 'claude-code-cli'
+          ELSE 'unknown-acp-agent' END)
+      ELSE lane.value END)
+    FROM json_each(grp.value, '$.lanes') AS lane
+  ))))
+  FROM json_each(payload, '$.executionGroups') AS grp
+))) WHERE json_type(payload, '$.executionGroups') = 'array';
+
+-- A ReviewRound holds at most one Group, so only the Lane array nests here.
+UPDATE review_rounds SET payload = json_set(payload, '$.executionGroup.lanes', json((
+  SELECT json_group_array(CASE
+    WHEN json_type(lane.value, '$.effective') = 'object'
+    THEN json_set(lane.value, '$.effective.schemaVersion', 4,
+      '$.effective.component', CASE json_extract(lane.value, '$.effective.adapterId')
+        WHEN 'codex' THEN 'codex-cli'
+        WHEN 'claude' THEN 'claude-code-cli'
+        ELSE 'unknown-acp-agent' END)
+    ELSE lane.value END)
+  FROM json_each(payload, '$.executionGroup.lanes') AS lane
+))) WHERE json_type(payload, '$.executionGroup.lanes') = 'array';
+`
+    },
+    {
+        version: 16,
+        name: "acp-session-run-configuration",
+        introducedIn: "0.15.10",
+        // An ACP Role binding may now carry a model, a reasoning effort and a
+        // permission strategy beyond `default`, because Yui's ACP client implements
+        // `session/set_config_option` and pushes those values to the Session before
+        // it prompts. Previously the adapter rejected all three, so no stored
+        // payload can contain them.
+        //
+        // This widens the contract without rewriting anything, and the absence of a
+        // payload update is the substantive decision rather than an omission. A v10
+        // ACP binding holds `permission.strategy = "default"`, which keeps exactly
+        // the meaning it always had: Yui sends no mode, so the Agent's own default
+        // stands. Rewriting those rows to `bypass` — or to any newly expressible
+        // value — would grant authority the user never chose, on Homes whose owner
+        // did nothing but upgrade. `bypass` is reachable only by asking for it.
+        //
+        // Effective launch snapshots need no change either. They already carry
+        // optional `model` and `effort` on the shared base, and their ACP permission
+        // is the same object the adapter canonicalizes, so a historical snapshot
+        // still validates unchanged at schemaVersion 4 across Sessions, Session
+        // history, Turns, WorkItem ExecutionLanes and ReviewRound ExecutionLanes.
+        // A frozen snapshot therefore keeps describing the launch it actually ran,
+        // which is what makes replaying old history honest.
+        sql: "SELECT 1; -- ACP bindings may carry model/effort and a chosen "
+            + "permission mode; existing `default` bindings keep their meaning"
+    },
+    {
+        version: 17,
+        name: "session-origin-input-requests",
+        introducedIn: "0.15.8",
+        // Widen requester provenance: notifications originate in a current Leader
+        // Session without an AgentRun. Existing schemaVersion-3 requests keep their
+        // exact Run/Session origin, including frozen historical Context values.
+        // No guessed native identity or history rewrite is needed.
+        sql: "SELECT 1; -- InputRequest requester.runId is optional when an exact nativeSessionId is present"
+    },
+    {
+        version: 18,
+        name: "replaceable-session-process-custody",
+        introducedIn: "0.15.8",
+        // Existing Session/Run history remains unchanged. Runtime mailboxes may
+        // now retain explicit replacement intent; OS owner records may identify
+        // the dedicated execution child, independently of a disposable Host.
+        sql: "SELECT 1; -- Replacement intent, independent retained native control evidence/process custody, and optional fixed TaskWake refs"
+    },
+    {
+        version: 19,
+        name: "task-artifacts-local-git",
+        introducedIn: "0.16.0",
+        // Retire the DB-owned immutable Artifact store: file/directory artifacts now
+        // live in a per-Task local Git repository, referenced by a self-certifying
+        // `commit + relativePath`. The whole rewrite is payload work that must READ
+        // the `artifacts` table before it is dropped, so it runs entirely in
+        // `migrateData` (which executes after this `sql`) — the table is dropped
+        // there, last, once its rows have been moved. Requirement A's independent,
+        // deterministic submit-intent backfill (events + id_sequences only) is the
+        // final step inside that same transaction. This `sql` is intentionally a
+        // no-op: dropping the table here would destroy the rows before they move.
+        //
+        // The 18->19 contract also DECLARES three optional `messages.payload` fields
+        // added by Requirement A — `intent` (record|discuss|develop), an optional
+        // client idempotency `submissionKey`, and a frozen `submissionReceipt`
+        // disposition. They add no column and no table and are only ever written
+        // going forward (absent `intent` reads as discuss; absent key is keyless;
+        // absent receipt is a pre-19 message), so NO historical row is rewritten and
+        // no key or receipt is ever fabricated for old data — declaring them here
+        // satisfies "optional still requires a migration declaration".
+        sql: "SELECT 1; -- artifacts move to per-Task local Git; see migrateArtifactsToGit",
+        migrateData: migrateArtifactsToGit
     }
 ]);
 for (let index = 0; index < MIGRATIONS.length; index += 1) {
@@ -713,8 +1159,9 @@ if (MIGRATIONS.at(-1)?.version !== CURRENT_STORAGE_VERSION) {
 /** Current hot-path indexes whose absence would invalidate a current Home. */
 const REQUIRED_SCHEMA_INDEXES = [
     "idx_mailboxes_ready",
-    "idx_runtime_session_cleanup_required",
-    "idx_input_requests_open_hot"
+    "idx_input_requests_open_hot",
+    "idx_turns_planning_active",
+    "idx_tasks_activation_pending"
 ];
 function checksum(sql) {
     return createHash("sha256").update(sql).digest("hex");
@@ -929,7 +1376,12 @@ export function migrateSqliteSchema(db, options) {
             throw new SqliteSchemaMigrationError(`storage version ${applied.currentVersion} is older than the minimum supported `
                 + `${MIN_SUPPORTED_STORAGE_VERSION}`, "admission");
         }
-        const pending = MIGRATIONS.filter((migration) => !applied.versions.has(migration.version));
+        // Production callers omit `throughVersion`, so the effective target is head
+        // and behavior is unchanged; a partial target is honored only in apply mode.
+        const effectiveTarget = options.mode === "apply" && options.throughVersion !== undefined
+            ? options.throughVersion
+            : CURRENT_STORAGE_VERSION;
+        const pending = MIGRATIONS.filter((migration) => !applied.versions.has(migration.version) && migration.version <= effectiveTarget);
         if (!ledgerWasCreated && pending.length > 0 && options.mode === "validate") {
             throw new SqliteSchemaMigrationError(`Storage version ${applied.currentVersion} requires an explicit upgrade to `
                 + `${CURRENT_STORAGE_VERSION}`, "admission");
@@ -937,12 +1389,17 @@ export function migrateSqliteSchema(db, options) {
         const newlyApplied = [];
         for (const migration of pending) {
             db.exec(migration.sql);
+            migration.migrateData?.(db);
             const appliedAt = new Date().toISOString();
             db.prepare(`INSERT INTO schema_migrations (version, name, applied_at, checksum)
          VALUES (?, ?, ?, ?)`).run(migration.version, migration.name, appliedAt, checksum(migration.sql));
             newlyApplied.push(migration.version);
         }
-        validateSchemaObjects(db);
+        // The table/index inventory describes the HEAD shape; only assert it once the
+        // migration has actually advanced to head (a deliberate partial target stops
+        // earlier and is validated when the real upgrade later completes it).
+        if (effectiveTarget >= CURRENT_STORAGE_VERSION)
+            validateSchemaObjects(db);
         return newlyApplied;
     };
     const newlyApplied = options.mode === "apply" && !db.inTransaction
@@ -952,6 +1409,10 @@ export function migrateSqliteSchema(db, options) {
 }
 /** The names of every table the schema creates (for tests/introspection). */
 export const SQLITE_SCHEMA_TABLES = [
+    "plugin_intents",
+    "plugin_validations",
+    "local_resources",
+    "environment_preparations",
     "schema_migrations",
     "home_meta",
     "config",
@@ -967,7 +1428,6 @@ export const SQLITE_SCHEMA_TABLES = [
     "coordination_locks",
     "integration_queue",
     "durable_jobs",
-    "job_caller_key_hashes",
     "outbox",
     "mailboxes",
     "task_records",