@zq-silk/yui 0.6.0 → 0.6.2

package/dist/runtime/sessionTerminationGuard.js

@@ -0,0 +1,211 @@
+export const DEFAULT_GRACEFUL_GRACE_MS = 3_000;
+export const DEFAULT_FORCED_GRACE_MS = 2_000;
+export const DEFAULT_TERMINATION_POLL_MS = 100;
+/**
+ * Stops one Role owner with physical exit proof.
+ *
+ * Sequence: graceful exact-owner tmux stop -> bounded grace -> forced
+ * SIGTERM/SIGKILL of the exact Provider root and its process group -> final
+ * /proc re-verification. Only when every owned root is absent (PID gone or
+ * start identity changed) does the result become `stop-confirmed`; otherwise
+ * the Session stays non-terminal and the caller must not commit `stopped`.
+ *
+ * PID reuse is handled structurally: liveness always pairs the PID with its
+ * recorded start identity, so a recycled PID is treated as absent and never
+ * signaled.
+ */
+export async function terminateSessionOwners(owner, records, ports, options = {}) {
+    const gracefulGraceMs = positiveDuration(options.gracefulGraceMs, DEFAULT_GRACEFUL_GRACE_MS, "gracefulGraceMs");
+    const forcedGraceMs = positiveDuration(options.forcedGraceMs, DEFAULT_FORCED_GRACE_MS, "forcedGraceMs");
+    const pollMs = positiveDuration(options.pollMs, DEFAULT_TERMINATION_POLL_MS, "pollMs");
+    const now = ports.now();
+    ports.emit({ stage: "stop-requested", owner, at: now });
+    let gracefulOk = true;
+    try {
+        gracefulOk = await ports.gracefulStop(owner);
+    }
+    catch (error) {
+        gracefulOk = false;
+        ports.emit({
+            stage: "graceful-stop",
+            owner,
+            detail: error instanceof Error ? error.message : String(error),
+            at: ports.now()
+        });
+    }
+    if (gracefulOk) {
+        ports.emit({ stage: "graceful-stop", owner, at: ports.now() });
+    }
+    if (records.length === 0) {
+        // No physical owner record: tmux-level cleanup is the only proof
+        // available. Report the gap rather than claiming physical zero.
+        return {
+            outcome: gracefulOk ? "stop-confirmed" : "stop-blocked",
+            owner,
+            confirmed: [],
+            remaining: [],
+            ...(gracefulOk
+                ? {}
+                : { verificationGap: "no-owner-record: tmux stop unconfirmed" })
+        };
+    }
+    // Bounded graceful grace: poll the exact owned trees for exit.
+    if (await waitForTreesAbsent(records, ports, gracefulGraceMs, pollMs)) {
+        ports.emit({ stage: "stop-confirmed", owner, at: ports.now() });
+        return {
+            outcome: "stop-confirmed",
+            owner,
+            confirmed: records,
+            remaining: []
+        };
+    }
+    // Forced escalation against the exact roots only. A root whose identity
+    // cannot be verified (verification gap) is never signaled: PID reuse
+    // safety requires pairing the PID with its start identity.
+    ports.emit({ stage: "forced-stop", owner, at: ports.now() });
+    for (const record of records) {
+        escalateRecord(record, ports, "SIGTERM");
+    }
+    await waitForTreesAbsent(records, ports, forcedGraceMs, pollMs);
+    for (const record of records) {
+        escalateRecord(record, ports, "SIGKILL");
+    }
+    await waitForTreesAbsent(records, ports, forcedGraceMs, pollMs);
+    const remaining = [];
+    const confirmed = [];
+    let verificationGap;
+    for (const record of records) {
+        const verdict = treeVerdict(record, ports);
+        if (verdict.kind === "absent") {
+            confirmed.push(record);
+            continue;
+        }
+        if (verdict.kind === "gap") {
+            verificationGap = `/proc unreadable for pid ${record.providerRoot.pid}`;
+            remaining.push({ record, detail: verificationGap });
+            continue;
+        }
+        const root = rootVerdict(record, ports);
+        remaining.push({
+            record,
+            detail: root.kind === "live"
+                ? `provider root pid ${record.providerRoot.pid} still live`
+                : `provider children still live for launch ${record.launchId}`
+        });
+    }
+    const outcome = remaining.length === 0 ? "stop-confirmed" : "stop-blocked";
+    ports.emit({
+        stage: outcome === "stop-confirmed" ? "stop-confirmed" : "stop-blocked",
+        owner,
+        ...(outcome === "stop-blocked"
+            ? {
+                detail: remaining
+                    .map(({ record, detail }) => `${record.launchId}: ${detail}`)
+                    .join("; ")
+            }
+            : {}),
+        at: ports.now()
+    });
+    return {
+        outcome,
+        owner,
+        confirmed,
+        remaining,
+        ...(verificationGap === undefined ? {} : { verificationGap })
+    };
+}
+function rootVerdict(record, ports) {
+    const { pid, startIdentity } = record.providerRoot;
+    const current = ports.processIdentity(pid);
+    if (current === undefined) {
+        // /proc unreadable or entry gone. Gone is absent; unreadable is a gap.
+        return ports.procEntryExists(pid) ? { kind: "gap" } : { kind: "absent" };
+    }
+    // A zombie has already exited; only the unreaped task struct remains. It
+    // cannot execute or hold resources, so it counts as absent for physical
+    // exit proof (the parent reaping the zombie does not change liveness).
+    if (current.state === "Z")
+        return { kind: "absent" };
+    return current.startIdentity === startIdentity
+        ? { kind: "live" }
+        : { kind: "absent" };
+}
+/**
+ * Verdict for the whole owned tree: the Provider root plus any surviving
+ * child carrying the exact launch fence. A verification gap counts as
+ * present: the grace polls must not short-circuit to `stop-confirmed` while
+ * `/proc` is unreadable, because that would claim physical zero without
+ * proof. The final verdict turns a persistent gap into `stop-blocked`.
+ */
+function treeVerdict(record, ports) {
+    const root = rootVerdict(record, ports);
+    if (root.kind === "live")
+        return { kind: "live" };
+    // The root is gone or unreadable: a surviving child carrying the exact
+    // launch fence keeps the tree live. Children without the fence are
+    // unattributed and never block confirmation on their own.
+    const fencedChildren = ports
+        .listLaunchFencedProcesses(record.launchId)
+        .filter((pid) => pid !== record.providerRoot.pid);
+    if (fencedChildren.length > 0)
+        return { kind: "live" };
+    return root;
+}
+/**
+ * Signals the exact root (only when its identity is verified) and, while the
+ * root is live, its process group. When the root has already exited but a
+ * fenced child survives, each fenced child is signaled individually: the
+ * group can no longer be proven ours once its leader is gone.
+ */
+function escalateRecord(record, ports, signal) {
+    const root = rootVerdict(record, ports);
+    if (root.kind === "live") {
+        try {
+            ports.signalProcess(record.providerRoot.pid, signal);
+        }
+        catch {
+            // The root may have exited between verdict and signal; the final
+            // verification is authoritative.
+        }
+        const { processGroupId } = record.providerRoot;
+        if (processGroupId !== undefined) {
+            try {
+                ports.signalProcessGroup(processGroupId, signal);
+            }
+            catch {
+                // Group may already be gone or the root may not be its leader.
+            }
+        }
+        return;
+    }
+    if (root.kind !== "absent")
+        return;
+    for (const pid of ports.listLaunchFencedProcesses(record.launchId)) {
+        if (pid === record.providerRoot.pid)
+            continue;
+        try {
+            ports.signalProcess(pid, signal);
+        }
+        catch {
+            // A child may have exited between scan and signal.
+        }
+    }
+}
+async function waitForTreesAbsent(records, ports, timeoutMs, pollMs) {
+    const start = Date.now();
+    for (;;) {
+        if (records.every((record) => treeVerdict(record, ports).kind === "absent")) {
+            return true;
+        }
+        if (Date.now() - start >= timeoutMs)
+            return false;
+        await ports.sleep(Math.min(pollMs, Math.max(1, timeoutMs - (Date.now() - start))));
+    }
+}
+function positiveDuration(value, fallback, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError(`${label} must be a positive integer.`);
+    }
+    return resolved;
+}

package/dist/runtime/taskRuntimeIsolation.js

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
+import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 export const YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR = "YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR";
 export const YUI_TASK_RUNTIME_SERVICE_NAMESPACE = "YUI_TASK_RUNTIME_SERVICE_NAMESPACE";
 const MARKER_FILE = ".yui-task-runtime-owner.json";
@@ -15,12 +16,16 @@ export class FileTaskRuntimeIsolation {
     #controlPlane;
     #pathLayout;
     #inspectResources;
+    #resourceRegistrarValue;
     constructor(options) {
         this.#runtimeRoot = canonicalPath(options.runtimeRoot, "Task runtime root");
         this.#controlPlane = normalizeControlBoundary(options.controlPlane);
         this.#pathLayout = taskRuntimePathLayout(options.pathLayout);
         this.#inspectResources = options.inspectResources;
     }
+    #resourceRegistrar() {
+        return this.#resourceRegistrarValue ??= new ResourceRegistrar(this.#controlPlane.yuiHome);
+    }
     preflight(input) {
         const descriptor = createTaskRuntimeIsolationDescriptor({
             ...input,
@@ -57,6 +62,7 @@ export class FileTaskRuntimeIsolation {
                 throw new Error(`Task runtime generation is not exactly owned: ${root}.`);
             }
             ensureOwnedDirectories(descriptor);
+            this.#resourceRegistrar().registerTaskRuntimeIsolation(descriptor);
             return;
         }
         ensureDirectoryChain(this.#runtimeRoot, dirname(root));
@@ -73,6 +79,7 @@ export class FileTaskRuntimeIsolation {
                 mode: 0o600
             });
             ensureOwnedDirectories(descriptor);
+            this.#resourceRegistrar().registerTaskRuntimeIsolation(descriptor);
         }
         catch (error) {
             const current = inspectGenerationRoot(descriptor, fingerprint);
@@ -113,6 +120,12 @@ export class FileTaskRuntimeIsolation {
                 throw new Error("Task runtime resources changed during cleanup claim.");
             }
             rmSync(claimed, { recursive: true });
+            this.#resourceRegistrar().markPathsDeleted([
+                descriptor.roots.generation,
+                descriptor.roots.data,
+                descriptor.roots.cache,
+                descriptor.roots.temporary
+            ]);
         }
         catch (error) {
             // Preserve a claimed-but-unverified resource. Restore its exact path only

package/dist/runtime/tmuxAdapters.js

@@ -11,12 +11,14 @@ export class TmuxSessionHost {
     tmux;
     #globalHostId;
     #createBindingId;
+    #onHostCreated;
     #launchTails = new Map();
     constructor(planner, tmux, options = {}) {
         this.planner = planner;
         this.tmux = tmux;
         this.#globalHostId = requireSafeIdentity(options.globalHostId ?? "operator", "Global tmux host id");
         this.#createBindingId = options.createBindingId ?? randomUUID;
+        this.#onHostCreated = options.onHostCreated;
     }
     async start(request, beforeHostStart) {
         return this.#launch(request, beforeHostStart);
@@ -190,7 +192,18 @@ export class TmuxSessionHost {
         });
         // Process creation is last: every local invariant has already passed.
         const hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
-        return createRuntimeBinding({
+        if (hostCreated
+            && request.owner.scope === "task"
+            && planned.launch.env.YUI_JOB_CALLER_KEY !== undefined
+            && this.planner.commitTaskCallerKey !== undefined) {
+            this.planner.commitTaskCallerKey({
+                taskId: request.owner.taskId,
+                roleName: request.owner.roleName,
+                agentId: request.agentId,
+                callerKey: planned.launch.env.YUI_JOB_CALLER_KEY
+            });
+        }
+        const binding = createRuntimeBinding({
             id: bindingId,
             launchId: request.launchId,
             owner: request.owner,
@@ -207,6 +220,13 @@ export class TmuxSessionHost {
                 : {}),
             ...(nativeSessionId === undefined ? {} : { nativeSessionId })
         });
+        if (hostCreated && this.#onHostCreated !== undefined) {
+            const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
+            if (pane !== undefined) {
+                this.#onHostCreated({ binding, pane });
+            }
+        }
+        return binding;
     }
 }
 /** Non-blocking receipt-backed tmux push; it never interprets provider output. */
@@ -238,6 +258,19 @@ async function probeRoleStatus(tmux, hostId, roleName) {
         ? tmux.probeRoleStatus(hostId, roleName)
         : tmux.probeRoleStatusAsync(hostId, roleName);
 }
+async function inspectRolePane(tmux, hostId, roleName) {
+    try {
+        return tmux.inspectRolePaneAsync === undefined
+            ? tmux.inspectRolePane?.(hostId, roleName)
+            : await tmux.inspectRolePaneAsync(hostId, roleName);
+    }
+    catch {
+        // The pane may have exited between creation and inspection; the owner
+        // recorder treats a missing pane as a verification gap, not a launch
+        // failure.
+        return undefined;
+    }
+}
 async function killRole(tmux, hostId, roleName) {
     if (tmux.killRoleAsync === undefined) {
         tmux.killRole(hostId, roleName);

package/dist/scheduler/actionability.js

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { isDurableJobTerminal } from "../job/durableJob.js";
+/**
+ * Canonical SHA-256 digest over the normalized actionable facts. Pure and
+ * deterministic: the same facts always produce the same digest regardless of
+ * collection order.
+ */
+export function computeActionabilityDigest(input) {
+    const facts = [...input.facts]
+        .map((fact) => ({ key: fact.key, value: fact.value }))
+        .sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+    const canonical = JSON.stringify({
+        taskId: input.taskId,
+        taskStatus: input.taskStatus,
+        facts
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+const TERMINAL_WORK_ITEM_STATUSES = new Set(["completed", "retired"]);
+const CONSUMED_INTEGRATION_STATUSES = new Set(["committed", "superseded"]);
+/**
+ * Fold a Task's durable records into the normalized actionable facts. This
+ * function only reads; it never starts a Controller, queues a wake, writes a
+ * Message, or mutates any record.
+ *
+ * Included facts (each changes only when the durable record changes):
+ * - Active Runs: the ownership/liveness picture. A Run starting or ending
+ *   changes the digest so a lost executor is detected.
+ * - Non-terminal/failed WorkItems: pending, running, awaiting-acceptance, and
+ *   failed items still need Leader or Worker action.
+ * - Non-completed ReviewRounds: pending/running/failed rounds still need
+ *   Leader disposition or a Reviewer.
+ * - Unresolved IntegrationAttempts: running/validating/blocked/failed attempts
+ *   the Leader may need to resolve.
+ * - Terminal DurableJobs: new terminal results the Leader should observe.
+ * - InputRequests: open and answered/cancelled requests.
+ * - User directives explicitly marked `wakePolicy=leader`.
+ *
+ * Excluded: pure revision growth, progress/heartbeat events, repeated scans of
+ * an unchanged blocker, read-only status requests, and waits already owned by
+ * an active Worker/Reviewer/Job (the active-Run facts above capture ownership).
+ */
+export function collectTaskActionability(store, taskId) {
+    const task = store.getTask(taskId);
+    if (task === null) {
+        throw new Error(`Task not found for actionability projection: ${taskId}.`);
+    }
+    const facts = [];
+    for (const run of store.listAgentRuns(taskId).filter((candidate) => candidate.status === "active")) {
+        facts.push({
+            key: `active-run:${run.id}`,
+            value: [
+                run.roleName,
+                run.workItemId ?? "",
+                run.reviewRoundId ?? "",
+                run.updatedAt
+            ].join("|")
+        });
+    }
+    for (const item of store.listWorkItems?.(taskId) ?? []) {
+        if (TERMINAL_WORK_ITEM_STATUSES.has(item.status))
+            continue;
+        facts.push({
+            key: `work-item:${item.id}`,
+            value: `${item.status}|${item.updatedAt}`
+        });
+    }
+    for (const round of store.listReviewRounds?.(taskId) ?? []) {
+        if (round.status === "completed")
+            continue;
+        facts.push({
+            key: `review:${round.id}`,
+            value: `${round.status}|${round.endedAt ?? round.createdAt}`
+        });
+    }
+    for (const attempt of store.listIntegrationAttempts?.(taskId) ?? []) {
+        if (CONSUMED_INTEGRATION_STATUSES.has(attempt.status))
+            continue;
+        facts.push({
+            key: `integration:${attempt.id}`,
+            value: `${attempt.status}|${attempt.updatedAt}`
+        });
+    }
+    for (const job of store.listDurableJobs?.(taskId) ?? []) {
+        if (!isDurableJobTerminal(job.status))
+            continue;
+        facts.push({
+            key: `durable-job:${job.id}`,
+            value: `${job.status}|${job.terminalAt ?? job.updatedAt}`
+        });
+    }
+    for (const request of store.listInputRequests?.(taskId) ?? []) {
+        facts.push({
+            key: `input:${request.id}`,
+            value: `${request.status}|${request.updatedAt}`
+        });
+    }
+    for (const message of store.listMessages?.(taskId) ?? []) {
+        if (message.wakePolicy !== "leader")
+            continue;
+        facts.push({
+            key: `directive:${message.id}`,
+            value: message.createdAt
+        });
+    }
+    return { taskId, taskStatus: task.status, facts };
+}
+/**
+ * Derive the Leader Run disposition from the Task execution projection status.
+ * This is machine-derived at yield time so the Scheduler does not depend on
+ * free-text Leader summaries.
+ */
+export function deriveLeaderRunDisposition(projectionStatus, taskStatus) {
+    if (taskStatus !== "active")
+        return "completed";
+    switch (projectionStatus) {
+        case "blocked":
+            return "blocked";
+        case "waiting-on-agents":
+        case "waiting-user":
+            return "waiting";
+        case "completed":
+        case "retired":
+        case "archived":
+            return "completed";
+        default:
+            return "progress";
+    }
+}
+/**
+ * Decide whether a `task-orphaned` scan should create a new Leader Run.
+ *
+ * Suppression applies only when the last Leader Run ended `waiting` or
+ * `blocked` and its `observedActionabilityDigest` equals the current digest.
+ * A `progress`/`completed` disposition, a missing digest, or a changed digest
+ * always wakes. Computation errors fail open.
+ */
+export function decideOrphanWake(input) {
+    const { currentDigest, lastLeaderRun } = input;
+    if (lastLeaderRun === null)
+        return { kind: "wake", digest: currentDigest };
+    if (lastLeaderRun.status === "active")
+        return { kind: "wake", digest: currentDigest };
+    const disposition = lastLeaderRun.disposition;
+    if (disposition !== "waiting" && disposition !== "blocked") {
+        return { kind: "wake", digest: currentDigest };
+    }
+    const observed = lastLeaderRun.observedActionabilityDigest;
+    if (observed === undefined)
+        return { kind: "wake", digest: currentDigest };
+    if (observed === currentDigest) {
+        return { kind: "suppress", digest: currentDigest, observedDigest: observed };
+    }
+    return { kind: "wake", digest: currentDigest };
+}

package/dist/scheduler/activeRoleRunDelivery.js

@@ -1,7 +1,7 @@
 import { selectedSchedulerRoles, selectedSchedulerTasks } from "./ports.js";
 import { isSchedulerTaskWorkspaceReady } from "./ports.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
-import { effectiveLaunchSnapshotsCompatible } from "../executor/effectiveLaunch.js";
+import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain } from "../executor/effectiveLaunch.js";
 import { RuntimeLaunchError } from "../runtime/ports.js";
 import { isPreInputReadinessSupported } from "../lifecycle/canonicalLifecycleEvent.js";
 import { preInputReadinessCapability } from "../lifecycle/providerLifecycleMapping.js";
@@ -328,7 +328,7 @@ function requireResumeSession(role, effective, session) {
     if (session === null || !hasText(session.nativeSessionId)) {
         throw new Error(`Role resume has no fixed native session: ${role.taskId}/${role.name}.`);
     }
-    if (!effectiveLaunchSnapshotsCompatible(session.effective, effective)) {
+    if (!effectiveLaunchSnapshotsCompatibleForTaskMain(session.effective, effective, role.managedWorkspace)) {
         throw new Error(`Role resume effective snapshot drifted: ${role.taskId}/${role.name}.`);
     }
     return session.nativeSessionId;
@@ -376,18 +376,27 @@ function validateRoleSession(role, effective, existing, mode, session) {
     if (session.agentId !== effective.agentId || session.adapterId !== effective.adapterId) {
         throw new Error(`Ready Role session identity changed: ${role.taskId}/${role.name}.`);
     }
-    if (!effectiveLaunchSnapshotsCompatible(session.effective, effective)) {
+    const compatible = mode === "resume"
+        ? effectiveLaunchSnapshotsCompatibleForTaskMain(session.effective, effective, role.managedWorkspace)
+        : effectiveLaunchSnapshotsCompatible(session.effective, effective);
+    if (!compatible) {
         throw new Error(`Ready Role session effective snapshot changed: ${role.taskId}/${role.name}.`);
     }
     if (existing?.nativeSessionId !== undefined
-        && effectiveLaunchSnapshotsCompatible(existing.effective, effective)
+        && effectiveLaunchSnapshotsCompatibleForTaskMain(existing.effective, effective, role.managedWorkspace)
         && session.nativeSessionId !== existing.nativeSessionId) {
         throw new Error(`Ready Role session changed the fixed native session id: ${role.taskId}/${role.name}.`);
     }
     if (mode === "resume" && session.nativeSessionId !== existing?.nativeSessionId) {
         throw new Error(`Role resume changed the fixed native session id: ${role.taskId}/${role.name}.`);
     }
-    return { ...session, status: "running" };
+    return {
+        ...session,
+        status: "running",
+        ...(mode === "resume" && existing !== null
+            ? { effective: existing.effective }
+            : {})
+    };
 }
 function hasText(value) {
     return typeof value === "string" && value.trim().length > 0;

package/dist/scheduler/activeTaskProgress.js

@@ -1,10 +1,19 @@
 import { selectedSchedulerTasks, isSchedulerTaskWorkspaceReady } from "./ports.js";
 import { queueLeaderWakeup } from "./wakeupQueue.js";
 import { projectTaskExecution } from "./taskExecutionProjection.js";
+import { collectTaskActionability, computeActionabilityDigest, decideOrphanWake } from "./actionability.js";
 /**
  * Repairs an active Task that has no durable owner capable of advancing it.
  * This is a low-frequency safety net; normal transitions enqueue their own
  * Role mailbox signal in the same transaction.
+ *
+ * Issue 05: a `task-orphaned` wake is suppressed when the last Leader Run
+ * ended waiting/blocked and its observed actionability digest equals the
+ * current digest. Suppression is silent — no Message, Event, or progress
+ * record is written — because a periodic scan that changes nothing is Yui
+ * engineering behavior with no Task-visible effect. Computation errors fail
+ * open: the Task is woken once and the error is recorded so it can never be
+ * silently starved.
  */
 export function repairOrphanedActiveTasks(store, now, selection) {
     const repaired = [];
@@ -36,6 +45,13 @@ export function repairOrphanedActiveTasks(store, now, selection) {
             || hasUnclaimedLeaderWork(store, task.id, leaderMailbox)) {
             continue;
         }
+        // Issue 05: digest-based admission. Only the "no-executor" orphan path
+        // reaches here; every other needs-leader-action state already has a
+        // durable owner (candidate, integration, or pending wake) and is exempt.
+        if (projection.reason === "no-executor") {
+            if (admitOrphanWake(store, task.id) === "suppress")
+                continue;
+        }
         const taskWorkspace = store.getTaskWorkspace(task.id);
         if (!isSchedulerTaskWorkspaceReady(task, taskWorkspace)) {
             store.queueTaskProgress(task.id, "task-orphaned", now);
@@ -55,6 +71,50 @@ export function repairOrphanedActiveTasks(store, now, selection) {
     }
     return repaired;
 }
+/**
+ * Decide whether one `task-orphaned` scan should wake the Leader. Returns
+ * `"suppress"` without writing anything when the digest is unchanged since
+ * the last waiting/blocked Leader Run. Computation errors fail open.
+ */
+function admitOrphanWake(store, taskId) {
+    let digest;
+    try {
+        const input = collectTaskActionability(store, taskId);
+        digest = computeActionabilityDigest(input);
+    }
+    catch (error) {
+        // Fail open: wake once and record the computation error so the Task can
+        // never be silently starved by a broken projection.
+        store.queueTaskProgress(taskId, "actionability-unknown", new Date());
+        return "wake";
+    }
+    const lastLeaderRun = findLastLeaderRun(store, taskId);
+    const decision = decideOrphanWake({ currentDigest: digest, lastLeaderRun });
+    return decision.kind === "suppress" ? "suppress" : "wake";
+}
+/**
+ * The most recent Leader Run (terminal or active). Active Runs are returned
+ * so the admission check never suppresses while a Leader is still running.
+ */
+function findLastLeaderRun(store, taskId) {
+    const runs = store.listAgentRuns?.(taskId) ?? [];
+    let latest = null;
+    for (const run of runs) {
+        if (run.roleName !== "leader")
+            continue;
+        if (latest === null || run.createdAt > latest.createdAt)
+            latest = run;
+    }
+    if (latest === null)
+        return null;
+    return {
+        status: latest.status,
+        ...(latest.disposition === undefined ? {} : { disposition: latest.disposition }),
+        ...(latest.observedActionabilityDigest === undefined
+            ? {}
+            : { observedActionabilityDigest: latest.observedActionabilityDigest })
+    };
+}
 function hasUnclaimedLeaderWork(store, taskId, leaderMailbox) {
     if (leaderMailbox === null)
         return store.getPendingWakeup(taskId) !== null;