@zq-silk/yui 0.15.8 → 0.15.11

package/dist/storage/sqliteSchema.js

@@ -23,6 +23,10 @@
 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 { migrateIntegrationContinuation } from "./migrations/integrationContinuation.js";
+import { UNIFY_HOME_LAYOUT_SQL, migrateUnifyHomeLayout } from "./migrations/unifyHomeLayout.js";
+import { COLLAPSE_WORKTREE_LAYOUT_SQL, migrateCollapseWorktreeLayout } from "./migrations/collapseWorktreeLayout.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_RUN = 200;
@@ -642,6 +646,27 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_context_snapshots_scope_sequence
   ON context_snapshots(task_id, scope, COALESCE(scope_ref, ''), sequence);
 `;
+/**
+ * The Global-owned Message store (decision-3 §9/§11). It extends the Message
+ * store to a Global owner exactly as `global_role_session_sets` parallels
+ * `role_session_sets`: keyed by the Global Role `name` with an FK to
+ * `global_roles`, never by a fabricated `task_id`, and never a new private
+ * queue. Ids are minted from the existing `global_sequences` counter, so a
+ * Global input has an explicit owner and an authorizable reference without
+ * reusing Task record shapes or Task permissions.
+ */
+const GLOBAL_ROLE_MESSAGE_SQL = `
+CREATE TABLE IF NOT EXISTS global_role_messages (
+  name       TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  seq        INTEGER NOT NULL,
+  payload    TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (name, message_id),
+  FOREIGN KEY (name) REFERENCES global_roles(name)
+);
+CREATE INDEX IF NOT EXISTS idx_global_role_messages_seq ON global_role_messages(name, seq);
+`;
 const MIGRATION_1_SQL = [
     BASELINE_CORE_SQL,
     BASELINE_JOB_AND_RELEASE_SQL,
@@ -1117,6 +1142,128 @@ UPDATE review_rounds SET payload = json_set(payload, '$.executionGroup.lanes', j
         // 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
+    },
+    {
+        version: 20,
+        name: "integration-conflict-continuation",
+        introducedIn: "0.16.0",
+        // Widen Integration status with conflicted; declare optional sourceProgress
+        // (Git cursor/reflog action) and checkInputDigest. Exact old bound FF Job
+        // receipts supply these facts; unprovable history remains unchanged.
+        // Frozen Context and events are never rewritten.
+        sql: "SELECT 1; -- Integration Git progress and exact check admission",
+        migrateData: migrateIntegrationContinuation
+    },
+    {
+        version: 21,
+        name: "force-archive-independent-cleanup",
+        introducedIn: "0.16.0",
+        // Declare optional task.archived force/cleanup/warnings/retainedResources
+        // audit fields and task.archive-cleanup resource/status/detail/paths events;
+        // runtime.event-obsolete may retain the full originalEvent as source evidence.
+        // Archived Tasks may retain exact runtime/workspace/mailbox ownership.
+        // Existing archive, completion and Publication history is unchanged.
+        sql: "SELECT 1; -- archive intent and cleanup evidence remain separate facts"
+    },
+    {
+        version: 22,
+        name: "controller-owned-agent-host-ingress",
+        introducedIn: "0.16.0",
+        // Add optional `host` source metadata to the stable Inbox v1 observation
+        // envelope. Such facts contain no resolved Run: current Controller alone
+        // validates ownership and commits observations, process custody and native
+        // account locations. Existing Inbox facts and domain history stay intact.
+        // Host status capabilities/transport diagnostics are live, not stored.
+        sql: "SELECT 1; -- Controller-owned Host ingress; no historical data rewrite"
+    },
+    {
+        version: 23,
+        name: "unified-message-input-control",
+        introducedIn: "0.16.1",
+        // Widen the Message payload with an optional durable input action
+        // (queue/steer) plus its stable requestId, and an optional interrupt-then
+        // handoff claim (requestId + exact target AgentRun). Existing messages carry
+        // neither field and keep their current queue semantics and delivery history;
+        // no native Turn identity is synthesized and no history is rewritten. The
+        // same contiguous migration adds the Global-owned Message store
+        // (global_role_messages), extending the Message store to a Global owner
+        // exactly as global_role_session_sets parallels role_session_sets: an
+        // explicit Global owner and authorizable reference, no fabricated Task and
+        // no new private global queue (decision-3 §9/§11).
+        sql: `SELECT 1; -- Message input actions, exact Session delivery pins, provider receipts and interrupt-then claims; Global Session provider bindings and native interrupt evidence\n${GLOBAL_ROLE_MESSAGE_SQL}`
+    },
+    {
+        version: 24,
+        name: "unify-home-layout",
+        introducedIn: "0.15.9",
+        // Unify every Yui self-managed path under a single canonical YUI_HOME. The
+        // managed Git worktrees move from the out-of-Home `defaultWorkspace` into
+        // `<home>/workspaces/{worktree,tasks}` and the provider runtimes from the
+        // `<home>.task-runtimes` sibling into `<home>/runtime/task-runtimes`. Only
+        // the durable Git worktree tree is physically relocated, by COPY (never
+        // rename-away): its replica is digest-verified against the source and
+        // atomically published while the original is PRESERVED as the rollback
+        // anchor; the regenerable task views and disposable runtimes are pointer
+        // rewrites only. The copied worktrees are then repaired, and only the
+        // persisted pointers the runtime trusts as live are rewritten. Frozen
+        // evidence (Context snapshots, terminal Run Git evidence, candidate
+        // snapshots, terminal Jobs, reports) and self-healing/self-rediscovered
+        // records (Task cwd, active Role workspaces, views, resource registry) are
+        // left intact; a queued/running Job bound under a relocating root is refused
+        // rather than silently moved. The data/filesystem transform is the
+        // substantive step; the SQL is inert.
+        sql: UNIFY_HOME_LAYOUT_SQL,
+        migrateData: migrateUnifyHomeLayout
+    },
+    {
+        version: 25,
+        name: "collapse-worktree-layout",
+        introducedIn: "0.15.9",
+        // Collapse the two-layer managed workspace layout into a single layer of real
+        // Git worktrees addressed by Task/owner and Project. Each managed worktree
+        // moves from its per-Project physical root
+        // (`<home>/workspaces/worktree/<projectName>/<taskKey>/<roleKey>`) to the
+        // location the v19 symlink view used to point at
+        // (`<home>/workspaces/tasks/<taskId>/<owner>/<projectDirectory>`), so the
+        // logical entry path and the physical worktree become the same directory and
+        // the symlink-view indirection is gone; an integration attempt moves under a
+        // new `tasks/<taskId>/integrations/<id>/` owner root, addressed by the bound
+        // Project directory rather than the Project name. Only the durable Git
+        // worktrees are physically relocated, by COPY (never rename-away): each
+        // replica is digest-verified against the source and atomically published over
+        // the regenerable view symlink while the original is PRESERVED as the
+        // rollback anchor. The copied worktrees are then repaired, and only the
+        // persisted pointers the runtime trusts as live are rewritten. Frozen
+        // evidence and self-healing records are left intact; a queued/running Job
+        // bound under a relocating worktree is refused rather than silently moved.
+        // The data/filesystem transform is the substantive step; the SQL is inert.
+        sql: COLLAPSE_WORKTREE_LAYOUT_SQL,
+        migrateData: migrateCollapseWorktreeLayout
     }
 ]);
 for (let index = 0; index < MIGRATIONS.length; index += 1) {
@@ -1350,13 +1497,24 @@ 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");
         }
+        // Bound the applied steps to `throughVersion` (default and clamp: head), so a
+        // migration test can stop at one step's intermediate state while production
+        // always advances to head. The validate-mode guard above still fires on the
+        // FULL pending set — the bound never lets an ordinary open partially migrate.
+        const targetVersion = Math.min(options.throughVersion ?? CURRENT_STORAGE_VERSION, CURRENT_STORAGE_VERSION);
+        const toApply = pending.filter((migration) => migration.version <= targetVersion);
         const newlyApplied = [];
-        for (const migration of pending) {
+        for (const migration of toApply) {
             db.exec(migration.sql);
             migration.migrateData?.(db);
             const appliedAt = new Date().toISOString();
@@ -1364,19 +1522,26 @@ export function migrateSqliteSchema(db, options) {
          VALUES (?, ?, ?, ?)`).run(migration.version, migration.name, appliedAt, checksum(migration.sql));
             newlyApplied.push(migration.version);
         }
-        validateSchemaObjects(db);
-        return newlyApplied;
+        // 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);
+        // The true head reached: the highest already-applied version or, when this
+        // run advanced the ledger, the last step it committed. Bounded runs report
+        // the intermediate head; an unbounded run reports CURRENT_STORAGE_VERSION.
+        const head = newlyApplied.at(-1) ?? applied.currentVersion;
+        return { newlyApplied, head };
     };
-    const newlyApplied = options.mode === "apply" && !db.inTransaction
+    const outcome = options.mode === "apply" && !db.inTransaction
         ? db.transaction(migrate)()
         : migrate();
-    return { applied: newlyApplied, version: CURRENT_STORAGE_VERSION };
+    return { applied: outcome.newlyApplied, version: outcome.head };
 }
 /** The names of every table the schema creates (for tests/introspection). */
 export const SQLITE_SCHEMA_TABLES = [
     "plugin_intents",
     "plugin_validations",
-    "artifacts",
     "local_resources",
     "environment_preparations",
     "schema_migrations",
@@ -1387,6 +1552,7 @@ export const SQLITE_SCHEMA_TABLES = [
     "projects",
     "global_roles",
     "global_role_session_sets",
+    "global_role_messages",
     "global_sequences",
     "tasks_catalog",
     "managed_workspaces",

package/dist/storage/sqliteStore.js

@@ -40,11 +40,12 @@ import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
 import { validatePluginValidation } from "../plugins/pluginPackage.js";
 import { validatePluginIntent, validatePluginIntentFailure } from "../plugins/pluginIntent.js";
-import { validateArtifact, validateLocalResource, validateEnvironmentPreparation } from "../resources/projectResource.js";
+import { validateLocalResource, validateEnvironmentPreparation } from "../resources/projectResource.js";
 import { validateConfiguredAgent } from "../agent/agent.js";
 import { validateTaskBrief } from "../brief/taskBrief.js";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
 import { validateContextSnapshot } from "../context/contextSnapshot.js";
+import { validateGlobalRoleMessage } from "../message/message.js";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { compareRuntimeSessionCandidates, projectRuntimeSessionCandidate } from "../runtime/runtimeSessionCandidate.js";
 import { sessionOwnerProcessKey } from "../runtime/sessionOwnerIdentity.js";
@@ -548,6 +549,8 @@ export class SqliteTaskStore {
             validateTaskRole(record);
         if (table === "global_roles")
             validateGlobalRole(record);
+        if (table === "global_role_messages")
+            validateGlobalRoleMessage(record);
         return record;
     }
     #sortById(rows, idOf) {
@@ -614,26 +617,6 @@ export class SqliteTaskStore {
         });
     }
     // -- projects ---------------------------------------------------------------
-    saveArtifact(artifact) {
-        validateArtifact(artifact);
-        this.#mutate(() => {
-            const previous = this.getArtifact(artifact.taskId, artifact.id);
-            if (previous !== null) {
-                if (!isDeepStrictEqual(previous, artifact))
-                    throw new StorageRecordError("Artifacts are immutable.");
-                return;
-            }
-            this.#db.prepare("INSERT INTO artifacts (task_id, id, payload) VALUES (?, ?, ?)")
-                .run(artifact.taskId, artifact.id, this.#json(artifact));
-        });
-    }
-    getArtifact(taskId, artifactId) {
-        const artifact = this.#getPayload("artifacts", "task_id = ? AND id = ?", [taskId, artifactId]);
-        return artifact === null ? null : validateArtifact(artifact);
-    }
-    listArtifacts(taskId) {
-        return this.#listPayload("artifacts", "task_id = ?", [taskId]).map(validateArtifact);
-    }
     savePluginValidation(validation) {
         validatePluginValidation(validation);
         this.#mutate(() => {
@@ -784,7 +767,7 @@ export class SqliteTaskStore {
                     activeRunRefs.push(`${task.id}/${run.id}`);
             }
             for (const attempt of this.listIntegrationAttempts(task.id)) {
-                if (attempt.status === "running" || attempt.status === "blocked") {
+                if (["running", "blocked", "conflicted", "validating"].includes(attempt.status)) {
                     unresolvedIntegrationRefs.push(`${task.id}/${attempt.id}`);
                 }
             }
@@ -875,6 +858,42 @@ export class SqliteTaskStore {
             this.#saveRuntimeSessionCandidate(sessions);
         });
     }
+    // -- global role messages ---------------------------------------------------
+    nextGlobalRoleMessageId() { return this.#nextGlobalId("global-message"); }
+    saveGlobalRoleMessage(message) {
+        validateGlobalRoleMessage(message);
+        this.#requireGlobalRole(message.roleName);
+        this.#mutate(() => {
+            const seq = this.#globalMessageSequence(message.id);
+            this.#db.prepare(`INSERT INTO global_role_messages (name, message_id, seq, payload, created_at) VALUES (?, ?, ?, ?, ?)`).run(message.roleName, message.id, seq, this.#json(message), message.createdAt);
+        });
+    }
+    listGlobalRoleMessages(roleName) {
+        return this.#sortById(this.#listPayload("global_role_messages", "name = ?", [roleName]), (message) => message.id);
+    }
+    updateGlobalRoleMessage(message) {
+        validateGlobalRoleMessage(message);
+        this.#requireGlobalRole(message.roleName);
+        this.#mutate(() => {
+            const seq = this.#globalMessageSequence(message.id);
+            const result = this.#db.prepare(`UPDATE global_role_messages SET seq = ?, payload = ? WHERE name = ? AND message_id = ?`).run(seq, this.#json(message), message.roleName, message.id);
+            if (result.changes === 0) {
+                throw new StorageRecordError(`Global message not found: ${message.roleName}/${message.id}`);
+            }
+        });
+    }
+    #requireGlobalRole(name) {
+        const row = this.#db.prepare("SELECT 1 FROM global_roles WHERE name = ?").get(name);
+        if (row === undefined)
+            throw new StorageRecordError(`Global Role not found: ${name}`);
+    }
+    /** A Global message id is `global-message-<n>`; its numeric tail is its seq. */
+    #globalMessageSequence(id) {
+        const match = /^global-message-([1-9]\d*)$/.exec(id);
+        if (match === null)
+            throw new StorageRecordError(`Global message id is invalid: ${id}`);
+        return Number(match[1]);
+    }
     // -- tasks ------------------------------------------------------------------
     nextTaskId() { return this.#nextGlobalId("task"); }
     saveTask(task) {

package/dist/storage/storageVersions.js

@@ -13,4 +13,4 @@
  * intermediate Yui releases.
  */
 export const MIN_SUPPORTED_STORAGE_VERSION = 1;
-export const CURRENT_STORAGE_VERSION = 18;
+export const CURRENT_STORAGE_VERSION = 25;

package/dist/storage/storeRpc.js

@@ -29,7 +29,7 @@ import { StorageCancelledError, StorageConflictError, StorageRecordError } from
  */
 const READ_ONLY_STORE_METHODS = new Set([
     "getPluginIntent", "listPluginIntents",
-    "getPluginValidation", "getArtifact", "listArtifacts", "getLocalResource", "listLocalResources",
+    "getPluginValidation", "getLocalResource", "listLocalResources",
     "getEnvironmentPreparation", "listEnvironmentPreparations",
     "rootDirectory",
     "getConfig",
@@ -46,6 +46,7 @@ const READ_ONLY_STORE_METHODS = new Set([
     "getGlobalRole",
     "getGlobalRoleSessionSet",
     "listGlobalRoleSessionSets",
+    "listGlobalRoleMessages",
     "listTasks",
     "getTask",
     "readNextActionFacts",

package/dist/storage/upgrade/upgradeOrchestrator.js

@@ -1,6 +1,7 @@
-import { basename, dirname, join } from "node:path";
+import { join } from "node:path";
 import { copyFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import Database from "better-sqlite3";
+import { inspectAgentHostCompatibility, describeAgentHostUpgradeBlockers } from "../../runtime/agentHostCompatibility.js";
 import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation } from "../../runtime/runtimeObservation.js";
 import { RUNTIME_PROCESS_EXIT_TASK_EVENT, validateRuntimeProcessExitObservation } from "../../runtime/processExitObservation.js";
 import { validateAgentProfile } from "../../profile/agentProfile.js";
@@ -10,6 +11,9 @@ import { validateRun } from "../../agentRun/agentRun.js";
 import { validateDurableJob } from "../../job/durableJob.js";
 import { validateWorkItem } from "../../workItem/workItem.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
+import { storageBackupRoot } from "../homeLayout.js";
+import { preflightUnifyHomeLayout } from "../migrations/unifyHomeLayout.js";
+import { preflightCollapseWorktreeLayout } from "../migrations/collapseWorktreeLayout.js";
 import { migrateSqliteSchema, storageMigrationPlan } from "../sqliteSchema.js";
 import { CURRENT_DATABASE_FILENAME, inspectStorageSchema } from "../storageSchema.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../storageVersions.js";
@@ -38,6 +42,15 @@ export async function runStorageUpgrade(options) {
             ? classification.classification.blocker.action
             : "Use a compatible Yui release.");
     }
+    const incompatibleHosts = await inspectAgentHostCompatibility(options.home);
+    if (incompatibleHosts.length > 0) {
+        return {
+            ...blocked(state.status === "current" ? currentClassification() : migratableClassification(state.currentVersion), "host-compatibility", `Existing Agent Hosts cannot safely use the target Controller/storage:\n${describeAgentHostUpgradeBlockers(incompatibleHosts)}`, "Keep the current Controller, Home and Host processes unchanged. Inspect the named Sessions and original pending "
+                + "inputs/results; let current work settle, then use explicitly authorized Session replacement/cleanup at a safe "
+                + "boundary before retrying the upgrade. This target cannot hot-patch legacy Host memory."),
+            hosts: incompatibleHosts
+        };
+    }
     if (state.status === "current") {
         try {
             validateCurrentStore(options.home);
@@ -73,6 +86,21 @@ export async function runStorageUpgrade(options) {
             + `to ${CURRENT_STORAGE_VERSION}.`), "corruption", "The storage migration registry is incomplete.", "Install a Yui release that carries the complete migration chain.");
     }
     const classification = migratableClassification(state.currentVersion);
+    // Genuine pre-migration safety check, shared by ALL migrating modes. The
+    // unify-home data migration (18->19) physically relocates on-disk trees and
+    // rewrites live launch pointers, so before any mode proceeds we run its READ-
+    // ONLY preflight and refuse up front on the same conditions the migration would
+    // throw on inside the apply transaction: a queued/running Job bound under a
+    // relocating root, or a conflicting relocation target. The migration is applied
+    // offline (after the operator has stopped this Home's writers), so the preflight
+    // does not scan for live processes. Surfacing these here — before the Controller
+    // is stopped or a backup is taken — is what makes `--dry-run` and the updater's
+    // `--update-preflight` a genuine readiness signal rather than a mere list of
+    // schema steps, while the in-transaction checks remain the authoritative guard
+    // against anything that starts after this point.
+    const migrationBlocked = preflightMigrationBlockers(options.home, plan, classification);
+    if (migrationBlocked !== null)
+        return migrationBlocked;
     if (options.mode === "update-preflight") {
         return {
             outcome: "update-preflight",
@@ -223,7 +251,10 @@ async function createDatabaseBackup(home, sourceVersion, now) {
     const source = join(home, CURRENT_DATABASE_FILENAME);
     if (!existsSync(source))
         throw new Error("The authoritative yui.db is missing.");
-    const backupDirectory = join(dirname(home), `${basename(home)}-backups`);
+    // Backups live inside Home so a single canonical root contains every
+    // self-managed artifact; the upgrade fence still protects them from the
+    // live database because they are a distinct partition from yui.db.
+    const backupDirectory = storageBackupRoot(home);
     mkdirSync(backupDirectory, { recursive: true, mode: 0o700 });
     const timestamp = now.toISOString().replaceAll(":", "-");
     const backupPath = join(backupDirectory, `pre-storage-v${sourceVersion}-${timestamp}.db`);
@@ -313,6 +344,68 @@ function blocked(classification, stage, message, action) {
         sceneUnchanged: true
     };
 }
+/**
+ * Run each path-relocating data migration's READ-ONLY preflight against the
+ * current (pre-upgrade) database and, when any finds a blocker, return a
+ * `blocked` result the caller surfaces before touching the Controller or the
+ * Home. Returns `null` when the plan carries no path-relocating data migration,
+ * or when every preflight is clear.
+ *
+ * Both the 18->19 unify and the 19->20 collapse migrations physically relocate
+ * managed worktrees and share the same blocker shape (in-flight Job, conflicting
+ * relocation target). When a Home is upgraded across both in one run, their
+ * blockers are aggregated so the operator sees every readiness problem at once.
+ *
+ * The database is opened read-only so the checks cannot mutate the authoritative
+ * store, and the handle is always closed. An unexpected failure to evaluate a
+ * preflight is itself a fail-closed blocker: we must not advance to an
+ * irreversible migration on an unverifiable readiness signal.
+ */
+function preflightMigrationBlockers(home, plan, classification) {
+    const relocatesUnify = plan.some((step) => step.name === "unify-home-layout");
+    const relocatesCollapse = plan.some((step) => step.name === "collapse-worktree-layout");
+    // Only meaningful when the plan actually includes a path-relocating migration.
+    if (!relocatesUnify && !relocatesCollapse)
+        return null;
+    let blockers;
+    try {
+        const database = new Database(join(home, CURRENT_DATABASE_FILENAME), {
+            readonly: true,
+            fileMustExist: true
+        });
+        try {
+            blockers = [];
+            if (relocatesUnify)
+                blockers.push(...preflightUnifyHomeLayout(database).blockers);
+            if (relocatesCollapse)
+                blockers.push(...preflightCollapseWorktreeLayout(database).blockers);
+        }
+        finally {
+            database.close();
+        }
+    }
+    catch (error) {
+        return {
+            ...blocked(classification, "in-flight", `The storage migration readiness check could not be completed: ${messageOf(error)}`, "Resolve the reported problem, confirm no Job is queued or running against a managed "
+                + "workspace, then rerun the upgrade.")
+        };
+    }
+    if (blockers.length === 0)
+        return null;
+    return {
+        outcome: "blocked",
+        stage: "in-flight",
+        message: "Refusing to migrate: the Home is not safe to relocate under the current layout yet. "
+            + blockers.map((entry) => entry.detail).join("; ") + ".",
+        action: "Resolve the reported condition(s) — let a queued/running Job finish or cancel it, and "
+            + "clear any conflicting relocation target — then rerun the upgrade. The migration is applied "
+            + "offline, so first confirm the Controller and any execution writers for this Home are "
+            + "stopped. The authoritative Home is unchanged.",
+        blockers: blockers.map((entry) => ({ reason: entry.reason, detail: entry.detail })),
+        classification,
+        sceneUnchanged: true
+    };
+}
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/task/archiveDiagnostics.js

@@ -0,0 +1,128 @@
+import { createTaskEvent } from "../event/taskEvent.js";
+import { StorageRecordError, StorageConflictError, StorageCancelledError } from "../storage/taskStore.js";
+import { StorageSchemaError } from "../storage/storageSchema.js";
+import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
+export class ArchiveAuditPersistenceError extends Error {
+    constructor(cause) {
+        super(`Archive audit could not be persisted: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = "ArchiveAuditPersistenceError";
+    }
+}
+export function isArchivePersistenceFailure(error) {
+    return error instanceof ArchiveAuditPersistenceError
+        || error instanceof StorageRecordError || error instanceof StorageConflictError
+        || error instanceof StorageCancelledError || error instanceof StorageSchemaError
+        || (error instanceof Error && (("code" in error && String(error.code).startsWith("SQLITE_"))
+            || (error.cause !== undefined && error.cause !== error && isArchivePersistenceFailure(error.cause))));
+}
+/** Current resource references, not another cleanup queue or writable status. */
+export function archiveRetainedResources(store, task) {
+    const workspaces = store.listManagedWorkspaces(task.id);
+    const resources = workspaces.map(workspace => ({
+        resource: managedWorkspaceKey(workspace.owner),
+        detail: "Managed workspace retained; removal has not been recorded.",
+        paths: [workspace.root, ...workspace.entries.filter(e => e.access === "write").map(e => e.path)]
+    }));
+    if (task.cwd !== undefined && !workspaces.some(w => w.owner.type === "task")) {
+        resources.push({ resource: `task:${task.id}`, detail: "Task workspace reference retained.", paths: [task.cwd] });
+    }
+    for (const run of store.listRuns(task.id).filter(r => r.status === "active")) {
+        resources.push({ resource: `run:${task.id}/${run.id}`,
+            detail: `AgentRun remains active (${run.roleName}); archive is not stop evidence.` });
+    }
+    for (const job of store.listDurableJobs(task.id).filter(j => ["queued", "running", "unknown-needs-attention"].includes(j.status))) {
+        resources.push({ resource: `job:${task.id}/${job.id}`, detail: `DurableJob remains ${job.status}.` });
+    }
+    for (const attempt of store.listIntegrationAttempts(task.id).filter(a => ["running", "blocked", "conflicted", "validating"].includes(a.status))) {
+        resources.push({ resource: `integration-attempt:${task.id}/${attempt.id}`,
+            detail: `Integration remains ${attempt.status}.` });
+    }
+    for (const item of store.listWorkItems(task.id).filter(i => i.status === "open")) {
+        resources.push({ resource: `work-item:${task.id}/${item.id}`, detail: "WorkItem remains unaccepted." });
+    }
+    for (const round of store.listReviewRounds(task.id).filter(r => !["completed", "failed"].includes(r.status))) {
+        resources.push({ resource: `review-round:${task.id}/${round.id}`, detail: `Review remains ${round.status}.` });
+    }
+    for (const input of store.listInputRequests(task.id).filter(i => i.status === "open")) {
+        resources.push({ resource: `input:${task.id}/${input.id}`, detail: "Unresolved input preserved; not answered by archive." });
+    }
+    for (const role of store.listRoles(task.id)) {
+        const sessions = store.getTaskRoleSessionSet(task.id, role.name);
+        for (const session of Object.values(sessions?.sessions ?? {})) {
+            if (session.status === "ended")
+                continue;
+            resources.push({ resource: `session:${task.id}/${role.name}/${session.agentId}/${session.nativeSessionId}`,
+                detail: `Session is ${session.status}; physical quiescence is not established by archive.` });
+        }
+        const provider = sessions?.providerBinding;
+        if (provider !== undefined && provider !== null && provider.run != null
+            && !["completed", "failed", "cancelled"].includes(provider.run.status)) {
+            resources.push({ resource: `provider-input:${task.id}/${role.name}/${provider.run.attemptId}`,
+                detail: `Provider input is ${provider.run.status}; exact input identity is retained.` });
+        }
+    }
+    for (const mailbox of store.listWorkMailboxes()) {
+        const target = mailbox.target;
+        if (!("taskId" in target) || target.taskId !== task.id)
+            continue;
+        if (mailbox.processing === null && mailbox.pending === null)
+            continue;
+        resources.push({
+            resource: `mailbox:${target.kind}:${task.id}${"roleName" in target ? `/${target.roleName}` : ""}`,
+            detail: `Original mailbox retained${mailbox.processing === null ? "" : ` (${mailbox.processing.batchId})`}; not replayed or acknowledged by archive.`
+        });
+    }
+    return resources;
+}
+export function archiveDeliveryWarnings(delivery) {
+    return delivery.projects.filter(p => p.codeDelivery !== "none" && (!p.merged || !p.verified))
+        .map(p => ({ resource: `delivery:${delivery.taskId}/${p.projectId}`,
+        detail: `${p.coverage}: ${p.reason} Merged=${p.merged}; verified=${p.verified}.` }));
+}
+/** Every completed/failed resource attempt is committed before trying the next.
+ * Do not catch storage failures: callers must not report unrecorded cleanup as success.
+ */
+export function recordArchiveCleanup(store, taskId, diagnostic, status, now = new Date()) {
+    try {
+        store.transaction(tx => {
+            if (tx.getTask(taskId)?.status !== "archived")
+                throw new Error(`Task is not archived: ${taskId}.`);
+            tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, "task.archive-cleanup", {
+                resource: diagnostic.resource, detail: diagnostic.detail, status,
+                ...(diagnostic.paths === undefined ? {} : { paths: JSON.stringify(diagnostic.paths) })
+            }, now));
+        });
+    }
+    catch (error) {
+        throw new ArchiveAuditPersistenceError(error);
+    }
+}
+export function taskArchiveDiagnostics(store, task) {
+    const events = store.listEvents(task.id);
+    const archive = events.filter(e => e.type === "task.archived").at(-1);
+    const cleanup = events.filter(e => e.type === "task.archive-cleanup");
+    const warnings = archive?.payload.warnings === undefined
+        ? [] : JSON.parse(archive.payload.warnings);
+    // These are historical attempt diagnostics; current references below remain
+    // authoritative even when explicit later resource cleanup has succeeded.
+    for (const event of cleanup.filter(e => e.payload.status === "retained")) {
+        warnings.push({ resource: event.payload.resource, detail: event.payload.detail,
+            ...(event.payload.paths === undefined ? {} : { paths: JSON.parse(event.payload.paths) }) });
+    }
+    const forced = archive?.payload.force === "true";
+    const cleanupFinished = !forced || cleanup.some(e => e.payload.status === "finished");
+    if (forced && !cleanupFinished)
+        warnings.push({ resource: `task:${task.id}`,
+            detail: "Archive committed; cleanup has not finished. Retained references require explicit inspection; archive retry does not replay cleanup." });
+    return { archived: task.status === "archived", forced,
+        disposition: archive?.payload.workspaceDisposition ?? null,
+        cleanupFinished, warnings, retainedResources: archiveRetainedResources(store, task),
+        cleanupEvents: cleanup };
+}
+export function renderArchiveDiagnostics(data) {
+    return [
+        `Archived: ${data.archived}; forced: ${data.forced}; cleanup finished: ${data.cleanupFinished}`,
+        ...data.warnings.map(w => `Warning [${w.resource}]: ${w.detail}`),
+        ...data.retainedResources.map(r => `Retained [${r.resource}]: ${r.detail}${r.paths ? ` (${r.paths.join(", ")})` : ""}`)
+    ].join("\n") + "\n";
+}