@zq-silk/yui 0.6.0 → 0.6.2

package/dist/core/controllerTelemetry.js

@@ -0,0 +1,167 @@
+/**
+ * Pure-memory, fixed-space command observation for the Controller socket.
+ *
+ * The core server owns route/built-in command observation: every authenticated
+ * request is counted once at the routing layer, and a bounded unrefed scheduler
+ * samples event-loop delay so an already-written request's pre-dispatch wait is
+ * observable even when the loop is saturated by scheduler projections. The
+ * FileTaskController composes these snapshots into its runtime status metric;
+ * nothing here is persisted and every snapshot is O(1).
+ */
+const CONTROLLER_DELAY_BUCKETS_MS = [10, 50, 100, 250, 500, 1_000, 3_000];
+const DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS = 50;
+const BUILTIN_METHODS = new Set([
+    "controller.status",
+    "controller.identity",
+    "controller.stop",
+    "controller.begin-handover",
+    "controller.commit-handover",
+    "controller.rollback-handover",
+    "controller.handover-state"
+]);
+export function isBuiltinControllerMethod(method) {
+    return BUILTIN_METHODS.has(method);
+}
+export function monotonicMilliseconds() {
+    return Number(process.hrtime.bigint()) / 1_000_000;
+}
+export const productionTelemetryScheduler = {
+    setInterval: (callback, delayMs) => {
+        const timer = setInterval(callback, delayMs);
+        timer.unref();
+        return {
+            unref: () => timer.unref(),
+            close: () => clearInterval(timer)
+        };
+    }
+};
+/**
+ * Counts routed commands once at the routing layer. Built-in routes
+ * (controller.status/identity/stop) and dispatcher routes are observed
+ * separately so the dispatcher's own service-time metric cannot be mistaken
+ * for end-to-end latency and is never double-counted.
+ */
+export class ControllerCommandObserver {
+    #clock;
+    #received = 0;
+    #completed = 0;
+    #failed = 0;
+    #inFlight = 0;
+    /** Monotonic arrival timestamps of in-flight observations (FIFO). */
+    #inFlightStarted = [];
+    #builtinCompleted = 0;
+    #builtinFailed = 0;
+    #dispatchedCompleted = 0;
+    #dispatchedFailed = 0;
+    constructor(clock = monotonicMilliseconds) {
+        this.#clock = clock;
+    }
+    start() {
+        this.#received += 1;
+        this.#inFlight += 1;
+        this.#inFlightStarted.push(this.#clock());
+        let completed = false;
+        return {
+            complete: (kind, outcome) => {
+                if (completed)
+                    return;
+                completed = true;
+                this.#inFlight = Math.max(0, this.#inFlight - 1);
+                this.#inFlightStarted.shift();
+                this.#completed += 1;
+                if (outcome === "failure")
+                    this.#failed += 1;
+                if (kind === "builtin") {
+                    if (outcome === "failure")
+                        this.#builtinFailed += 1;
+                    else
+                        this.#builtinCompleted += 1;
+                }
+                else if (outcome === "failure") {
+                    this.#dispatchedFailed += 1;
+                }
+                else {
+                    this.#dispatchedCompleted += 1;
+                }
+            }
+        };
+    }
+    snapshot() {
+        const oldest = this.#inFlightStarted.length === 0
+            ? null
+            : Math.max(0, this.#clock() - this.#inFlightStarted[0]);
+        return {
+            received: this.#received,
+            completed: this.#completed,
+            failed: this.#failed,
+            inFlight: this.#inFlight,
+            oldestInFlightAgeMs: oldest,
+            builtin: {
+                completed: this.#builtinCompleted,
+                failed: this.#builtinFailed
+            },
+            dispatched: {
+                completed: this.#dispatchedCompleted,
+                failed: this.#dispatchedFailed
+            }
+        };
+    }
+}
+/**
+ * Bounded event-loop delay sampler. A fixed-cadence unrefed interval measures
+ * how much later than expected it fires; that lag is the pre-dispatch wait an
+ * already-written socket request experiences while the loop is busy. State is
+ * a fixed counter set plus seven bucket counters, so memory is constant and
+ * snapshots are O(1).
+ */
+export class ControllerEventLoopDelay {
+    #clock;
+    #scheduler;
+    #intervalMs;
+    #handle;
+    #expectedAt = 0;
+    #samples = 0;
+    #maximumLagMs = 0;
+    #buckets = new Map(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [threshold, 0]));
+    #stopped = false;
+    constructor(clock = monotonicMilliseconds, scheduler = productionTelemetryScheduler, intervalMs = DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS) {
+        this.#clock = clock;
+        this.#scheduler = scheduler;
+        this.#intervalMs = intervalMs;
+    }
+    start() {
+        if (this.#handle !== undefined || this.#stopped)
+            return;
+        this.#expectedAt = this.#clock() + this.#intervalMs;
+        this.#handle = this.#scheduler.setInterval(() => this.#sample(), this.#intervalMs);
+    }
+    #sample() {
+        if (this.#stopped)
+            return;
+        const lag = Math.max(0, this.#clock() - this.#expectedAt);
+        this.#expectedAt = this.#clock() + this.#intervalMs;
+        this.#samples += 1;
+        const bounded = Math.ceil(lag);
+        this.#maximumLagMs = Math.max(this.#maximumLagMs, bounded);
+        for (const threshold of CONTROLLER_DELAY_BUCKETS_MS) {
+            if (bounded <= threshold) {
+                this.#buckets.set(threshold, (this.#buckets.get(threshold) ?? 0) + 1);
+            }
+        }
+    }
+    stop() {
+        this.#stopped = true;
+        this.#handle?.close();
+        this.#handle = undefined;
+    }
+    snapshot() {
+        return {
+            samples: this.#samples,
+            maximumLagMs: this.#maximumLagMs,
+            lagBuckets: Object.fromEntries(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [
+                `le${threshold}ms`,
+                this.#buckets.get(threshold) ?? 0
+            ]))
+        };
+    }
+}

package/dist/doctor/doctor.js

@@ -1,5 +1,6 @@
 import { accessSync, constants, existsSync, lstatSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
+import Database from "better-sqlite3";
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { operationalAgentEnvironment } from "../agent/launchEnvironment.js";
 import { inspectAgentCapabilities, resolveAgentAdapter } from "../executor/agentAdapter.js";
@@ -11,8 +12,12 @@ import { defaultTableWidth, renderTable } from "../output/table.js";
 import { resolveYuiHome, STORAGE_STATE_FILE } from "../storage/taskStore.js";
 import { createProductionStorageRegistry, openCompatibleFileTaskStore, validateCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
+import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 import { classifyHome } from "../storage/upgrade/homeClassification.js";
+import { readMigrationReceipt } from "../storage/upgrade/migrationReceipt.js";
 import { latestStorageVersionState } from "../storage/upgrade/recordVersions.js";
+import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigration.js";
 import { CommandExecutionError } from "../tmux/commandExecutor.js";
 import { EPHEMERAL_DOMAIN_GRACE_MS, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 /**
@@ -42,12 +47,68 @@ export function summarizeStorageHealth(checks) {
 /** Build the full machine-readable doctor report (checks + storage health). */
 export function buildDoctorReport(env, executor, storageOptions = {}) {
     const inspection = inspectDoctor(env, executor, storageOptions);
+    const home = resolveYuiHome(env);
     return {
         checks: inspection.checks,
-        storage: summarizeStorageHealth(inspection.checks),
+        storage: {
+            ...summarizeStorageHealth(inspection.checks),
+            details: inspectStorageDetails(home, env)
+        },
         review: inspection.review
     };
 }
+/**
+ * Read the physical-backend facts for a Home (Issue 01 observability). Every
+ * field is best-effort read-only evidence: an unreadable database or manifest
+ * yields `null` for that field, and the `storage state` check reports the
+ * structural problem separately.
+ */
+function inspectStorageDetails(home, env) {
+    const schema = inspectStorageSchema(home);
+    const logicalLayout = schema.status === "current" || schema.status === "unsupported"
+        ? schema.currentLayoutVersion
+        : null;
+    const authoritativeBackend = resolveTaskStoreBackendForHome(home, env);
+    const dbPath = join(home, COMMITTED_DATABASE_FILENAME);
+    const databasePath = existsSync(dbPath) ? dbPath : null;
+    let journalMode = null;
+    let lastCommittedRevision = null;
+    if (databasePath !== null) {
+        try {
+            const db = new Database(databasePath, { readonly: true });
+            try {
+                const mode = db.pragma("journal_mode", { simple: true });
+                journalMode = typeof mode === "string" ? mode : String(mode);
+                const row = db.prepare("SELECT revision FROM home_meta WHERE id = 1").get();
+                lastCommittedRevision = typeof row?.revision === "number" ? row.revision : null;
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch {
+            // Leave both null; the storage state check surfaces the corruption.
+        }
+    }
+    else {
+        try {
+            const state = JSON.parse(readFileSync(join(home, STORAGE_STATE_FILE), "utf8"));
+            lastCommittedRevision = typeof state.revision === "number" ? state.revision : null;
+        }
+        catch {
+            lastCommittedRevision = null;
+        }
+    }
+    return {
+        logicalLayout,
+        authoritativeBackend,
+        databasePath,
+        journalMode,
+        workerEnabled: resolveStoreWorkerEnabledForHome(home, env),
+        migrationReceipt: readMigrationReceipt(home),
+        lastCommittedRevision
+    };
+}
 /** Runs the read-only FileTaskStore diagnostics used by `yui doctor`. */
 export function runDoctorCommand(args, env, executor, storageOptions = {}) {
     if (args.length !== 0)
@@ -170,13 +231,14 @@ function checkSchema(state, compatibility) {
                 detail: `current=${state.currentVersion} latest=${state.latestVersion}`
             };
         case "unsupported":
-            if (compatibility.storageStatus === "compatible-old"
+            if ((compatibility.storageStatus === "compatible-old"
+                || compatibility.storageStatus === "needs-storage-repair")
                 && compatibility.check.status === "ok") {
                 return {
                     name: "storage schema",
                     status: "ok",
                     detail: `current=${state.currentVersion} latest=${state.latestVersion} `
-                        + `direction=${state.direction}; compatible-old validated`
+                        + `direction=${state.direction}; ${compatibility.storageStatus} validated`
                 };
             }
             return {
@@ -228,7 +290,11 @@ function inspectCompatibility(home, homeCheck, schema, storageOptions) {
         return { check: { name, status: "invalid", detail: errorMessage(error) } };
     }
     const storageStatus = classification.classification.status;
-    if (storageStatus === "compatible-old") {
+    // A pseudo-layout-7 Home (needs-storage-repair) opens through the same
+    // normalization path as compatible-old, so its records get the same eager
+    // validation before the schema check can treat a version mismatch as
+    // validated (Issue 01).
+    if (storageStatus === "compatible-old" || storageStatus === "needs-storage-repair") {
         try {
             validateCompatibleFileTaskStore(home, resolvedStorageOptions);
         }
@@ -239,7 +305,7 @@ function inspectCompatibility(home, homeCheck, schema, storageOptions) {
                 check: {
                     name,
                     status: "invalid",
-                    detail: `unsupported compatible-old shape: ${errorMessage(error)}`
+                    detail: `unsupported ${storageStatus} shape: ${errorMessage(error)}`
                 }
             };
         }
@@ -276,6 +342,21 @@ function inspectCompatibility(home, homeCheck, schema, storageOptions) {
                     detail: `migration-required (MIGRATABLE) ${versions}; run yui update when Sessions are clear`
                 }
             };
+        case "needs-storage-repair":
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: {
+                    name,
+                    // Diagnostic mode (Issue 01 rollout step 1): the Home is readable
+                    // and usable, but the manifest claims layout 7 without a yui.db.
+                    // Surface the repair need in the detail while keeping the Home
+                    // healthy so ordinary commands keep working.
+                    status: "ok",
+                    detail: `needs-storage-repair (NEEDS_STORAGE_REPAIR) ${versions}; `
+                        + "the manifest claims layout 7 but yui.db is missing. Run `yui upgrade` to rebuild it from state.json."
+                }
+            };
         case "unsupported": {
             const unsupported = classification.classification;
             return {
@@ -308,25 +389,41 @@ function inspectState(home, homeCheck, schema, compatibility) {
         return blockedStorage("invalid", schema.detail);
     if (schema.status === "read-error")
         return blockedStorage("invalid", schema.detail);
-    if (compatibility.check.status !== "ok") {
+    // A pseudo-layout-7 Home (needs-storage-repair) has a readable state.json;
+    // the compatibility check surfaces the repair need, but the store itself is
+    // readable, so the state and review checks must still run (Issue 01).
+    if (compatibility.check.status !== "ok"
+        && compatibility.storageStatus !== "needs-storage-repair") {
         return blockedStorage(compatibility.check.status, storageBlockerDetail(compatibility.check));
     }
     if (compatibility.storageStatus !== "current"
-        && compatibility.storageStatus !== "compatible-old") {
+        && compatibility.storageStatus !== "compatible-old"
+        && compatibility.storageStatus !== "needs-storage-repair") {
         return blockedStorage("unsupported", compatibility.check.detail);
     }
     if (compatibility.storageOptions === undefined) {
         return blockedStorage("invalid", "Storage compatibility options were not resolved.");
     }
     const statePath = join(home, STORAGE_STATE_FILE);
-    if (!existsSync(statePath))
-        return blockedStorage("missing", "run yui setup");
-    try {
-        const metadata = lstatSync(statePath);
-        if (!metadata.isFile() || metadata.isSymbolicLink()) {
-            return blockedStorage("invalid", `${STORAGE_STATE_FILE} must be a regular file.`);
+    // A repaired layout-7 Home archived state.json; yui.db is the authoritative
+    // backend then, so the state.json gate is skipped (Issue 01).
+    const sqliteAuthoritative = !existsSync(statePath)
+        && existsSync(join(home, COMMITTED_DATABASE_FILENAME));
+    if (!sqliteAuthoritative) {
+        if (!existsSync(statePath))
+            return blockedStorage("missing", "run yui setup");
+        try {
+            const metadata = lstatSync(statePath);
+            if (!metadata.isFile() || metadata.isSymbolicLink()) {
+                return blockedStorage("invalid", `${STORAGE_STATE_FILE} must be a regular file.`);
+            }
+            accessSync(statePath, constants.R_OK);
         }
-        accessSync(statePath, constants.R_OK);
+        catch (error) {
+            return blockedStorage("invalid", errorMessage(error));
+        }
+    }
+    try {
         const store = openCompatibleFileTaskStore(home, compatibility.storageOptions);
         const config = store.getConfig();
         const agents = store.listConfiguredAgents();
@@ -337,12 +434,12 @@ function inspectState(home, homeCheck, schema, compatibility) {
             check: {
                 name: "storage state",
                 status: "ok",
-                detail: `readable agents=${agents.length} tasks=${tasks.length} roles=${roleCount} globalRoles=${globalRoles.length} defaultAgent=${config.defaultAgent ?? "none"}`
+                detail: `${sqliteAuthoritative ? "yui.db readable" : "readable"} agents=${agents.length} tasks=${tasks.length} roles=${roleCount} globalRoles=${globalRoles.length} defaultAgent=${config.defaultAgent ?? "none"}`
             },
             agents,
             review: {
                 storageReady: true,
-                storageDetail: "state.json is readable",
+                storageDetail: sqliteAuthoritative ? "yui.db is readable" : "state.json is readable",
                 ...(config.review === undefined ? {} : { policy: config.review }),
                 ...(config.review === undefined
                     ? {}

package/dist/domain/validation.js

@@ -51,3 +51,12 @@ export function normalizedUniqueIdentities(values, label) {
 export function cloneJson(value) {
     return JSON.parse(JSON.stringify(value));
 }
+/**
+ * True for a concrete, pinnable package version — a semver-shaped `X.Y.Z` with
+ * an optional pre-release/build suffix. Rejects dist-tag sentinels (`latest`,
+ * `next`, …), empty/whitespace, and anything not anchored to a numeric
+ * `major.minor.patch` so a moving tag can never be frozen into a release plan.
+ */
+export function isConcreteVersion(value) {
+    return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.trim());
+}

package/dist/execution/executionGroup.js

@@ -72,7 +72,8 @@ export function assertExecutionTargetUnchanged(group, target) {
  * Enforce the only durable Group/Lane evolution accepted by both domain
  * helpers and storage. Identity, target, prior results, and a final Leader
  * resolution never move backwards. A terminal Lane may only reopen as an
- * explicit retry with a fresh Run identity.
+ * explicit retry with a fresh Run identity, or reset to pending for a
+ * Task-final Review execution retry.
  */
 export function assertExecutionGroupTransition(existing, candidate) {
     validateExecutionGroup(existing);
@@ -101,7 +102,7 @@ export function assertExecutionGroupTransition(existing, candidate) {
         if (next === undefined) {
             throw new Error(`ExecutionGroup cannot remove Lane: ${lane.id}.`);
         }
-        assertExecutionLaneTransition(lane, next, existing.id);
+        assertExecutionLaneTransition(lane, next, existing.id, existing.purpose);
     }
 }
 export function isExecutionGroupTransition(existing, candidate) {
@@ -180,6 +181,32 @@ export function restartExecutionLane(group, laneId, patch, now) {
         updatedAt: timestamp
     });
 }
+/**
+ * Resets a terminal Reviewer Lane to pending without replacing its ExecutionGroup.
+ * The old AgentRun remains the attempt trail; clearing the Lane's Run/session and
+ * result lets the same semantic ReviewRound be dispatched again.
+ */
+export function resetReviewExecutionLane(group, laneId, now) {
+    validateExecutionGroup(group);
+    if (group.purpose !== "review") {
+        throw new Error(`Only Review ExecutionLanes can reset to pending: ${group.id}/${laneId}.`);
+    }
+    if (group.resolution !== undefined) {
+        throw new Error(`ExecutionGroup is already resolved: ${group.id}.`);
+    }
+    const existing = group.lanes.find((lane) => lane.id === laneId);
+    if (existing === undefined)
+        throw new Error(`ExecutionLane not found: ${group.id}/${laneId}.`);
+    if (!isTerminalLane(existing.status))
+        return existing;
+    const timestamp = now.toISOString();
+    const { effective: _effective, runId: _runId, sessionId: _sessionId, result: _result, endedAt: _endedAt, ...base } = existing;
+    return validateExecutionLane({
+        ...base,
+        status: "pending",
+        updatedAt: timestamp
+    }, group);
+}
 export function recordExecutionLaneResult(group, laneId, result, status, now) {
     const checked = validateLaneResult(result);
     validateExecutionGroup(group);
@@ -509,7 +536,7 @@ function validateResolution(resolution, group) {
         throw new Error("Execution accept resolution cannot retain high-priority findings.");
     }
 }
-function assertExecutionLaneTransition(existing, candidate, groupId) {
+function assertExecutionLaneTransition(existing, candidate, groupId, groupPurpose) {
     if (existing.id !== candidate.id
         || existing.groupId !== candidate.groupId
         || existing.groupId !== groupId
@@ -525,6 +552,16 @@ function assertExecutionLaneTransition(existing, candidate, groupId) {
     if (isTerminalLane(existing.status)) {
         if (isDeepStrictEqual(existing, candidate))
             return;
+        if (groupPurpose === "review"
+            && candidate.status === "pending"
+            && candidate.effective === undefined
+            && candidate.runId === undefined
+            && candidate.sessionId === undefined
+            && candidate.result === undefined
+            && candidate.endedAt === undefined
+            && isDeepStrictEqual(existing.workspace, candidate.workspace)) {
+            return;
+        }
         if (candidate.status !== "running"
             || candidate.runId === undefined
             || candidate.runId === existing.runId) {

package/dist/executor/agentExecutor.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validatePendingTurnCompletion, validateRecentTurnIds } from "./turnCompletion.js";
-import { effectiveLaunchSnapshotsCompatible, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
+import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
 export function createRoleSessionSet(owner, activeAgentId, now) {
     const base = {
         owner: normalizeOwner(owner),
@@ -241,7 +241,7 @@ export function rememberRoleAgentCompletedTurn(set, agentId, nativeSessionId, tu
     };
     return validateRoleSessionSet(updated);
 }
-export function roleAgentSessionResumeMode(set, agentId, desired) {
+export function roleAgentSessionResumeMode(set, agentId, desired, workspace) {
     if (set === null)
         return "new";
     validateRoleSessionSet(set);
@@ -260,7 +260,10 @@ export function roleAgentSessionResumeMode(set, agentId, desired) {
         }
         return "new";
     }
-    if (effectiveLaunchSnapshotsCompatible(session.effective, desired))
+    const compatible = set.owner.scope === "task"
+        ? effectiveLaunchSnapshotsCompatibleForTaskMain(session.effective, desired, workspace)
+        : effectiveLaunchSnapshotsCompatible(session.effective, desired);
+    if (compatible)
         return "resume";
     if (session.status !== "stopped" && session.status !== "broken") {
         throw new Error(`Role Agent session is incompatible with the next effective launch: ${agentId}. `

package/dist/executor/effectiveLaunch.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
+import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
 export function resolveEffectiveLaunch(input) {
     validateDesiredRole(input.role);
@@ -71,6 +72,57 @@ export function effectiveLaunchSnapshotsCompatible(existing, desired) {
     };
     return isDeepStrictEqual(withoutDesiredRevision(existing), withoutDesiredRevision(desired));
 }
+/**
+ * A Task-owned main workspace is a mutable checkout: Integration advances its
+ * durable Git heads while an idle native Session keeps the immutable launch
+ * configuration with which it started. A later Run may resume that exact
+ * Session only when the current durable Task workspace proves that every
+ * non-commit workspace identity and every other launch field is unchanged.
+ * WorkItem, ReviewRound and ExecutionLane workspaces remain strict.
+ */
+export function effectiveLaunchSnapshotsCompatibleForTaskMain(existing, desired, workspace) {
+    if (effectiveLaunchSnapshotsCompatible(existing, desired))
+        return true;
+    validateEffectiveLaunchSnapshot(existing);
+    validateEffectiveLaunchSnapshot(desired);
+    if (workspace === null || workspace === undefined)
+        return false;
+    validateManagedWorkspace(workspace);
+    if (workspace.owner.type !== "task")
+        return false;
+    const durableWorkspace = {
+        root: workspace.root,
+        entries: workspace.entries.map((entry) => ({ ...entry }))
+    };
+    if (!isDeepStrictEqual(desired.workspace, durableWorkspace))
+        return false;
+    return isDeepStrictEqual(taskMainCompatibleSnapshot(existing), taskMainCompatibleSnapshot(desired));
+}
+/** Preserves a fixed Session's launch configuration while freezing fresh Task-main Git facts. */
+export function effectiveLaunchWithTaskMainWorkspace(existing, workspace) {
+    validateEffectiveLaunchSnapshot(existing);
+    validateManagedWorkspace(workspace);
+    if (workspace.owner.type !== "task") {
+        throw new Error("Only a Task-owned main workspace may refresh fixed Session Run evidence.");
+    }
+    return validateEffectiveLaunchSnapshot({
+        ...existing,
+        workspace: {
+            root: workspace.root,
+            entries: workspace.entries.map((entry) => ({ ...entry }))
+        }
+    });
+}
+function taskMainCompatibleSnapshot(snapshot) {
+    const { sourceDesiredRevision: _sourceDesiredRevision, workspace, ...launch } = snapshot;
+    return {
+        ...launch,
+        workspace: {
+            root: workspace.root,
+            entries: workspace.entries.map(({ baseCommit: _baseCommit, ...entry }) => entry)
+        }
+    };
+}
 export function validateEffectiveLaunchSnapshot(snapshot) {
     if (snapshot.schemaVersion !== 2) {
         throw new Error("Effective launch snapshot must use schemaVersion 2.");

package/dist/executor/executorRegistry.js

@@ -1,5 +1,14 @@
 import { createHash } from "node:crypto";
 import { createPromptEnvelope, createSessionLaunchRequest } from "../runtime/index.js";
+/**
+ * rr13/test: Test-only liveness seam. Integration tests that spawn a real
+ * Controller subprocess cannot inject a fake TmuxDeliveryPort, and a saved
+ * active Leader Run would be reaped by the startup liveness pass without a
+ * real tmux role. When this env var is "1", every role reads "present"
+ * without probing tmux. The Controller subprocess inherits it from the
+ * test's CLI env. Never set in production.
+ */
+const TEST_ROLE_LIVENESS_PRESENT = process.env.YUI_TEST_ROLE_LIVENESS_PRESENT === "1";
 /**
  * Scheduler-to-tmux adapter. It retains only in-process prepared launch data;
  * durable session identity remains owned by FileTaskStore.
@@ -39,6 +48,16 @@ export class ExecutorRegistry {
         if (this.runtimePorts === undefined) {
             planned = this.planner.plan(input);
             sessionStarted = this.tmux.ensureRoleWindow(input.taskId, planned.role, planned.launch);
+            if (sessionStarted
+                && planned.launch.env.YUI_JOB_CALLER_KEY !== undefined
+                && this.planner.commitTaskCallerKey !== undefined) {
+                this.planner.commitTaskCallerKey({
+                    taskId: input.taskId,
+                    roleName: input.roleName,
+                    agentId: input.agentId,
+                    callerKey: planned.launch.env.YUI_JOB_CALLER_KEY
+                });
+            }
             session = planned.session;
         }
         else {
@@ -108,6 +127,7 @@ export class ExecutorRegistry {
         this.#prepared.set(delivery.deliveryId, {
             delivery,
             session,
+            workspace: input.workspace,
             ...(planned === undefined ? {} : { planned }),
             ...(binding === undefined ? {} : { binding })
         });
@@ -127,6 +147,27 @@ export class ExecutorRegistry {
             if (runId === undefined) {
                 throw new Error("Runtime prompt delivery requires a Task-local Run id.");
             }
+            // A reused native process retains the stable descriptor path from its
+            // original control plane. Publish only the current-control source after
+            // the Run/Session fence is durable and immediately before provider input;
+            // the reused Hook self-refreshes its own source before the volatile
+            // fence instead of the Controller scanning history to keep it fresh.
+            if (prepared.binding.hostCreated === false
+                && this.planner.refreshTaskRuntimeDescriptor !== undefined) {
+                if (!hasText(prepared.binding.nativeSessionId)) {
+                    throw new Error("Runtime prompt delivery requires a native Session id.");
+                }
+                this.planner.refreshTaskRuntimeDescriptor({
+                    taskId: input.delivery.prepared.taskId,
+                    roleName: input.delivery.prepared.roleName,
+                    runId,
+                    launchId: prepared.binding.launchId,
+                    nativeSessionId: prepared.binding.nativeSessionId,
+                    agentId: prepared.binding.agentId,
+                    adapterId: prepared.binding.adapterId,
+                    workspace: prepared.workspace
+                });
+            }
             const outcome = await this.runtimePorts.promptPush.tryPush({
                 binding: prepared.binding,
                 envelope: createPromptEnvelope({
@@ -172,6 +213,8 @@ export class ExecutorRegistry {
         }
     }
     async inspectRole(input) {
+        if (TEST_ROLE_LIVENESS_PRESENT)
+            return "present";
         const status = this.tmux.probeRoleStatusAsync === undefined
             ? this.tmux.probeRoleStatus(input.taskId, input.roleName)
             : await this.tmux.probeRoleStatusAsync(input.taskId, input.roleName);
@@ -198,6 +241,13 @@ export class ExecutorRegistry {
         }
     }
     async inspectRoles(inputs, resourceInputs) {
+        if (TEST_ROLE_LIVENESS_PRESENT) {
+            return inputs.map((input) => ({
+                taskId: input.taskId,
+                roleName: input.roleName,
+                status: "present"
+            }));
+        }
         if (this.tmux.inspectRolePaneInventory === undefined
             && this.tmux.inspectRolePaneInventoryAsync === undefined) {
             return Promise.all(inputs.map(async (input) => ({