@cjhyy/code-shell-capability-coding 0.8.0

package/dist/cc-orchestrator/external-agent-driver.js

@@ -0,0 +1,284 @@
+import { execFile, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { pathWithCommonBins } from "./cc-capability.js";
+import { killProcessGroup } from "@cjhyy/code-shell-core/extension";
+/** Pure: reduce collected output lines + exit code to a result. Unit-testable. */
+export function runWithLines(adapter, lines, exitCode) {
+    const parsed = adapter.parseResult(lines);
+    return { ...parsed, exitCode, lines };
+}
+const codexImageFlagCache = new Map();
+const CODEX_IMAGE_PROBE_TIMEOUT_MS = 5_000;
+const AGENT_TERMINATE_GRACE_MS = 500;
+function listPosixProcessTree(rootPid) {
+    return new Promise((resolve) => {
+        execFile("ps", ["-axo", "pid=,ppid="], { encoding: "utf8" }, (err, stdout) => {
+            if (err) {
+                resolve([rootPid]);
+                return;
+            }
+            const childrenByParent = new Map();
+            for (const line of stdout.split("\n")) {
+                const [pidText, parentText] = line.trim().split(/\s+/, 2);
+                const pid = Number(pidText);
+                const parentPid = Number(parentText);
+                if (!Number.isInteger(pid) || !Number.isInteger(parentPid))
+                    continue;
+                const children = childrenByParent.get(parentPid) ?? [];
+                children.push(pid);
+                childrenByParent.set(parentPid, children);
+            }
+            const pids = [];
+            const visit = (pid) => {
+                if (pids.includes(pid))
+                    return;
+                pids.push(pid);
+                for (const childPid of childrenByParent.get(pid) ?? [])
+                    visit(childPid);
+            };
+            visit(rootPid);
+            resolve(pids);
+        });
+    });
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForPidsToExit(pids, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while ([...pids].some(isPidAlive)) {
+        if (Date.now() >= deadline)
+            return false;
+        await delay(25);
+    }
+    return true;
+}
+function signalPids(pids, killSignal) {
+    for (const pid of pids) {
+        try {
+            process.kill(pid, killSignal);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+async function terminateAttachedProcessTree(child) {
+    const pid = child.pid;
+    if (!pid) {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // already gone
+        }
+        return;
+    }
+    if (process.platform === "win32") {
+        // Windows has no POSIX SIGTERM semantics or negative-pid groups. Reap the
+        // tree via taskkill, then use positive-pid process.kill as the fallback the
+        // platform supports when taskkill is unavailable/races.
+        await killProcessGroup(pid, { graceMs: AGENT_TERMINATE_GRACE_MS });
+        if (isPidAlive(pid)) {
+            try {
+                process.kill(pid);
+            }
+            catch {
+                // already gone
+            }
+        }
+        return;
+    }
+    const trackedPids = new Set(await listPosixProcessTree(pid));
+    signalPids(trackedPids, "SIGTERM");
+    if (await waitForPidsToExit(trackedPids, AGENT_TERMINATE_GRACE_MS))
+        return;
+    // Capture descendants created during the grace window while the leader is
+    // still addressable, but retain the first snapshot so reparented stubborn
+    // descendants cannot disappear from the escalation set.
+    for (const treePid of await listPosixProcessTree(pid))
+        trackedPids.add(treePid);
+    signalPids(trackedPids, "SIGKILL");
+    await waitForPidsToExit(trackedPids, 1_000);
+}
+function abortError() {
+    const err = new Error("Agent run aborted");
+    err.name = "AbortError";
+    return err;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError();
+}
+function createCodexImageProbe(command, cwd, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const child = spawn(command, ["exec", "--help"], {
+            cwd,
+            env: { ...process.env, PATH: pathWithCommonBins() },
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        let settled = false;
+        let terminating = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(err);
+        };
+        const onAbort = () => {
+            if (settled || terminating)
+                return;
+            terminating = true;
+            cleanup();
+            void terminateAttachedProcessTree(child).then(() => fail(abortError()));
+        };
+        const timer = setTimeout(() => {
+            if (settled || terminating)
+                return;
+            terminating = true;
+            cleanup();
+            void terminateAttachedProcessTree(child).then(() => done(false));
+        }, CODEX_IMAGE_PROBE_TIMEOUT_MS);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        child.stdout?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        child.on("error", () => {
+            if (!terminating)
+                done(false);
+        });
+        child.on("exit", () => {
+            if (!terminating)
+                done(/(?:^|\s)-i(?:,|\s)|--image\b/.test(out));
+        });
+    });
+}
+export function detectCodexImageInput(command, cwd, signal) {
+    if (signal)
+        return createCodexImageProbe(command, cwd, signal);
+    const cached = codexImageFlagCache.get(command);
+    if (cached)
+        return cached;
+    const probe = createCodexImageProbe(command, cwd);
+    codexImageFlagCache.set(command, probe);
+    return probe;
+}
+/** Spawn ONE headless agent run, collect stream-json to exit, return result.
+ *  No time concept — a single turn. Honors AbortSignal (kills the child). */
+export function runAgentOnce(adapter, opts, signal) {
+    return new Promise((resolve, reject) => {
+        void (async () => {
+            throwIfAborted(signal);
+            const codexImageInputSupported = adapter.kind === "codex" && (opts.imagePaths?.length ?? 0) > 0
+                ? await detectCodexImageInput(opts.command, opts.cwd, signal).catch((err) => {
+                    if (signal?.aborted || err?.name === "AbortError")
+                        throw err;
+                    return false;
+                })
+                : false;
+            throwIfAborted(signal);
+            const args = adapter.buildArgs({
+                prompt: opts.prompt,
+                resumeSessionId: opts.resumeSessionId,
+                model: opts.model,
+                permissionMode: opts.permissionMode ?? "default",
+                cwd: opts.cwd,
+                imagePaths: opts.imagePaths,
+                codexImageInputSupported,
+            });
+            throwIfAborted(signal);
+            // claude takes the prompt in argv (`-p <prompt>`) and wants stdin closed
+            // (verified: avoids a 3s wait). codex `exec` reads the prompt from stdin
+            // (argv ends with `-`), so adapters that set promptViaStdin get a piped
+            // stdin we write the prompt to.
+            const viaStdin = adapter.promptViaStdin === true;
+            const child = spawn(opts.command, args, {
+                cwd: opts.cwd,
+                env: { ...process.env, PATH: pathWithCommonBins() },
+                // Keep the agent in the owning worker/app process group. If that owner
+                // is force-terminated, the CLI and its descendants must not escape into
+                // a detached group that can keep editing the workspace unseen.
+                detached: false,
+                stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+            let settled = false;
+            let abortRequested = false;
+            let termination;
+            const cleanup = () => {
+                signal?.removeEventListener("abort", onAbort);
+            };
+            const onAbort = () => {
+                if (abortRequested)
+                    return;
+                abortRequested = true;
+                termination = terminateAttachedProcessTree(child);
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+            if (viaStdin && child.stdin) {
+                child.stdin.end(opts.prompt);
+            }
+            const lines = [];
+            if (child.stdout) {
+                const rl = createInterface({ input: child.stdout });
+                rl.on("line", (line) => lines.push(line));
+            }
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                // A missing binary is the most common failure (user hasn't installed the
+                // CLI, or GUI-launched Electron's PATH misses it). Turn the cryptic
+                // "spawn codex ENOENT" into something actionable that names the command.
+                if (err.code === "ENOENT") {
+                    reject(new Error(`未找到命令 "${opts.command}"。请先安装该 CLI 并确保它在 PATH 中（${adapter.kind === "codex" ? "Codex CLI" : "Claude Code CLI"}）。`));
+                    return;
+                }
+                reject(err);
+            });
+            child.on("exit", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                void (termination ?? Promise.resolve()).then(() => {
+                    resolve(runWithLines(adapter, lines, code));
+                });
+            });
+        })().catch(reject);
+    });
+}

package/dist/cc-orchestrator/external-agent-session-store.d.ts

@@ -0,0 +1,36 @@
+export type ExternalAgentCli = "claude" | "codex";
+export interface ExternalAgentSessionBinding {
+    cli: ExternalAgentCli;
+    sessionId: string;
+    codeShellSessionId?: string;
+    cwd: string;
+    workspaceRoot?: string;
+    worktreePath?: string;
+    worktreeBranch?: string;
+    worktreeBaseRef?: string;
+    isolation?: "current" | "worktree" | "none";
+    createdAt: number;
+    lastUsedAt: number;
+    /** @deprecated Use lastUsedAt. Kept while reading v1 snapshots. */
+    updatedAt: number;
+}
+export type ExternalAgentSessionRecord = Omit<ExternalAgentSessionBinding, "createdAt" | "lastUsedAt" | "updatedAt"> & {
+    createdAt?: number;
+    lastUsedAt?: number;
+    updatedAt?: number;
+};
+export declare function defaultExternalAgentSessionStorePath(): string;
+export declare class ExternalAgentSessionStore {
+    private readonly file;
+    constructor(file?: string);
+    /** Snapshot all known bindings. Returned objects are detached from the
+     *  persisted array so read-only consumers (for example room discovery) can
+     *  correlate worktree sessions without gaining a mutation path. */
+    list(): ExternalAgentSessionBinding[];
+    get(cli: ExternalAgentCli, sessionId: string): ExternalAgentSessionBinding | undefined;
+    record(binding: ExternalAgentSessionRecord): void;
+    private load;
+    private save;
+    private withLock;
+}
+export declare const externalAgentSessionStore: ExternalAgentSessionStore;

package/dist/cc-orchestrator/external-agent-session-store.js

@@ -0,0 +1,185 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { codeShellHome, logger, normalizeCwdPath } from "@cjhyy/code-shell-core/extension";
+const LOCK_WAIT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_POLL_MS = 10;
+export function defaultExternalAgentSessionStorePath() {
+    return join(codeShellHome(), "external-agent-sessions.json");
+}
+export class ExternalAgentSessionStore {
+    file;
+    constructor(file = defaultExternalAgentSessionStorePath()) {
+        this.file = file;
+    }
+    /** Snapshot all known bindings. Returned objects are detached from the
+     *  persisted array so read-only consumers (for example room discovery) can
+     *  correlate worktree sessions without gaining a mutation path. */
+    list() {
+        return this.load().map((binding) => ({ ...binding }));
+    }
+    get(cli, sessionId) {
+        if (!sessionId)
+            return undefined;
+        return this.load().find((s) => s.cli === cli && s.sessionId === sessionId);
+    }
+    record(binding) {
+        if (!binding.sessionId || !binding.cwd)
+            return;
+        this.withLock(() => {
+            const loaded = this.load();
+            const existing = loaded.find((s) => s.cli === binding.cli && s.sessionId === binding.sessionId);
+            const now = binding.lastUsedAt ?? binding.updatedAt ?? Date.now();
+            const next = {
+                cli: binding.cli,
+                sessionId: binding.sessionId,
+                ...((binding.codeShellSessionId ?? existing?.codeShellSessionId)
+                    ? { codeShellSessionId: binding.codeShellSessionId ?? existing?.codeShellSessionId }
+                    : {}),
+                cwd: normalizeCwdPath(binding.cwd),
+                ...((binding.workspaceRoot ?? existing?.workspaceRoot)
+                    ? { workspaceRoot: normalizeCwdPath(binding.workspaceRoot ?? existing.workspaceRoot) }
+                    : {}),
+                ...((binding.worktreePath ?? existing?.worktreePath)
+                    ? { worktreePath: normalizeCwdPath(binding.worktreePath ?? existing.worktreePath) }
+                    : {}),
+                ...((binding.worktreeBranch ?? existing?.worktreeBranch)
+                    ? { worktreeBranch: binding.worktreeBranch ?? existing?.worktreeBranch }
+                    : {}),
+                ...((binding.worktreeBaseRef ?? existing?.worktreeBaseRef)
+                    ? { worktreeBaseRef: binding.worktreeBaseRef ?? existing?.worktreeBaseRef }
+                    : {}),
+                ...((binding.isolation ?? existing?.isolation)
+                    ? { isolation: binding.isolation ?? existing?.isolation }
+                    : {}),
+                createdAt: binding.createdAt ?? existing?.createdAt ?? now,
+                lastUsedAt: now,
+                updatedAt: now,
+            };
+            const sessions = loaded.filter((s) => !(s.cli === binding.cli && s.sessionId === binding.sessionId));
+            sessions.push(next);
+            this.save(sessions);
+        });
+    }
+    load() {
+        if (!existsSync(this.file))
+            return [];
+        try {
+            const raw = readFileSync(this.file, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed || !Array.isArray(parsed.sessions))
+                return [];
+            return parsed.sessions.filter(isBinding).map(normalizeBinding);
+        }
+        catch (err) {
+            logger.warn("external_agent_session_store.load_failed", {
+                cat: "cc",
+                file: this.file,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return [];
+        }
+    }
+    save(sessions) {
+        const dir = dirname(this.file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const snapshot = { version: 2, sessions };
+        const tmp = `${this.file}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
+            renameSync(tmp, this.file);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
+    }
+    withLock(fn) {
+        const dir = dirname(this.file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        // TODO: move this sync polling lock to an async write queue; callers can
+        // otherwise block the event loop for up to LOCK_WAIT_MS under contention.
+        const lockDir = `${this.file}.lock`;
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        while (true) {
+            try {
+                mkdirSync(lockDir);
+                break;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EEXIST")
+                    throw err;
+                if (removeStaleLock(lockDir))
+                    continue;
+                if (Date.now() >= deadline) {
+                    throw new Error(`timed out waiting for external agent session store lock: ${lockDir}`, {
+                        cause: err,
+                    });
+                }
+                sleepSync(LOCK_POLL_MS);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            rmSync(lockDir, { recursive: true, force: true });
+        }
+    }
+}
+function normalizeBinding(binding) {
+    const updatedAt = finiteTimestamp(binding.updatedAt) ?? Date.now();
+    const lastUsedAt = finiteTimestamp(binding.lastUsedAt) ?? updatedAt;
+    const createdAt = finiteTimestamp(binding.createdAt) ?? lastUsedAt;
+    return {
+        ...binding,
+        cwd: normalizeCwdPath(binding.cwd),
+        ...(binding.workspaceRoot ? { workspaceRoot: normalizeCwdPath(binding.workspaceRoot) } : {}),
+        ...(binding.worktreePath ? { worktreePath: normalizeCwdPath(binding.worktreePath) } : {}),
+        createdAt,
+        lastUsedAt,
+        updatedAt: lastUsedAt,
+    };
+}
+function finiteTimestamp(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function removeStaleLock(lockDir) {
+    try {
+        if (Date.now() - statSync(lockDir).mtimeMs <= LOCK_STALE_MS)
+            return false;
+        rmSync(lockDir, { recursive: true, force: true });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return true;
+        return false;
+    }
+}
+function sleepSync(ms) {
+    try {
+        const view = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(view, 0, 0, ms);
+    }
+    catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) {
+            // fallback for runtimes where Atomics.wait is unavailable
+        }
+    }
+}
+function isBinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return ((v.cli === "claude" || v.cli === "codex") &&
+        typeof v.sessionId === "string" &&
+        v.sessionId.length > 0 &&
+        typeof v.cwd === "string" &&
+        v.cwd.length > 0);
+}
+export const externalAgentSessionStore = new ExternalAgentSessionStore();

package/dist/cc-orchestrator/index.d.ts

@@ -0,0 +1,10 @@
+/** External coding-agent orchestration surface. */
+export * from "./cc-capability.js";
+export * from "./agent-adapter.js";
+export * from "./external-agent-driver.js";
+export * from "./session-discovery.js";
+export * from "./codex-session-discovery.js";
+export * from "./related-session-discovery.js";
+export * from "./relevance-judge.js";
+export * from "./session-history.js";
+export * from "./codex-session-history.js";

package/dist/cc-orchestrator/index.js

@@ -0,0 +1,10 @@
+/** External coding-agent orchestration surface. */
+export * from "./cc-capability.js";
+export * from "./agent-adapter.js";
+export * from "./external-agent-driver.js";
+export * from "./session-discovery.js";
+export * from "./codex-session-discovery.js";
+export * from "./related-session-discovery.js";
+export * from "./relevance-judge.js";
+export * from "./session-history.js";
+export * from "./codex-session-history.js";

package/dist/cc-orchestrator/related-session-discovery.d.ts

@@ -0,0 +1,21 @@
+import { type ExternalAgentSessionBinding, type ExternalAgentCli } from "./external-agent-session-store.js";
+import { type DiscoveredSession, type DiscoverOptions } from "./session-discovery.js";
+export interface RelatedSessionDiscoveryOptions {
+    claudeHome?: string;
+    codexHome?: string;
+    /** Test seam; production reads DriveAgent's durable binding store. */
+    bindings?: readonly ExternalAgentSessionBinding[];
+}
+/**
+ * List sessions that belong to the selected cwd plus DriveAgent sessions
+ * launched in worktrees associated with it. The external CLI's own recorded
+ * cwd is retained on every row and becomes the authoritative path when opening
+ * the session.
+ */
+export declare function discoverRelatedSessions(cli: ExternalAgentCli, cwd: string, opts?: DiscoverOptions, discovery?: RelatedSessionDiscoveryOptions): DiscoveredSession[];
+/** Cheap total for the related-session list. Exact-cwd sessions come from the
+ * CLI index; delegated cwd totals come from durable DriveAgent bindings so we
+ * do not deep-read every transcript just to decide whether "load more" is
+ * needed. A stale binding can only overestimate this hint; loading all then
+ * returns the authoritative discovered length. */
+export declare function countRelatedSessions(cli: ExternalAgentCli, cwd: string, discovery?: RelatedSessionDiscoveryOptions): number;

package/dist/cc-orchestrator/related-session-discovery.js

@@ -0,0 +1,77 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { externalAgentSessionStore, } from "./external-agent-session-store.js";
+import { countSessions, discoverSessions, } from "./session-discovery.js";
+import { countCodexSessions, discoverCodexSessionsForCwds } from "./codex-session-discovery.js";
+/**
+ * List sessions that belong to the selected cwd plus DriveAgent sessions
+ * launched in worktrees associated with it. The external CLI's own recorded
+ * cwd is retained on every row and becomes the authoritative path when opening
+ * the session.
+ */
+export function discoverRelatedSessions(cli, cwd, opts = {}, discovery = {}) {
+    const root = resolve(cwd);
+    const bindings = discovery.bindings ?? externalAgentSessionStore.list();
+    const expectedIdsByCwd = new Map();
+    expectedIdsByCwd.set(root, new Set());
+    for (const binding of bindings) {
+        if (binding.cli !== cli || !isRelatedBinding(binding, root))
+            continue;
+        const bindingCwd = resolve(binding.cwd);
+        const ids = expectedIdsByCwd.get(bindingCwd) ?? new Set();
+        ids.add(binding.sessionId);
+        expectedIdsByCwd.set(bindingCwd, ids);
+    }
+    const candidateCwds = [...expectedIdsByCwd.keys()];
+    const candidates = cli === "codex"
+        ? discoverCodexSessionsForCwds(candidateCwds, discovery.codexHome ?? join(homedir(), ".codex"), opts, ({ sessionId, cwd: sessionCwd }) => {
+            const normalizedCwd = resolve(sessionCwd);
+            return (normalizedCwd === root || expectedIdsByCwd.get(normalizedCwd)?.has(sessionId) === true);
+        })
+        : candidateCwds.flatMap((candidateCwd) => discoverSessions(candidateCwd, discovery.claudeHome ?? join(homedir(), ".claude"), candidateCwd === root ? opts : { sinceMs: opts.sinceMs, now: opts.now }));
+    const deduped = new Map();
+    for (const session of candidates) {
+        const sessionCwd = resolve(session.cwd);
+        const expectedIds = expectedIdsByCwd.get(sessionCwd);
+        // The selected cwd shows every native CLI session. Related worktree cwd
+        // buckets show only sessions CodeShell actually delegated there.
+        if (sessionCwd !== root && !expectedIds?.has(session.sessionId))
+            continue;
+        const key = `${cli}:${session.sessionId}`;
+        const prior = deduped.get(key);
+        if (!prior || session.lastModified > prior.lastModified)
+            deduped.set(key, session);
+    }
+    let selected = [...deduped.values()].sort((a, b) => b.lastModified - a.lastModified);
+    if (opts.sinceMs && opts.sinceMs > 0) {
+        const cutoff = (opts.now ?? Date.now()) - opts.sinceMs;
+        selected = selected.filter((session) => session.lastModified >= cutoff);
+    }
+    if (opts.limit && opts.limit > 0)
+        selected = selected.slice(0, opts.limit);
+    return selected;
+}
+/** Cheap total for the related-session list. Exact-cwd sessions come from the
+ * CLI index; delegated cwd totals come from durable DriveAgent bindings so we
+ * do not deep-read every transcript just to decide whether "load more" is
+ * needed. A stale binding can only overestimate this hint; loading all then
+ * returns the authoritative discovered length. */
+export function countRelatedSessions(cli, cwd, discovery = {}) {
+    const root = resolve(cwd);
+    const exact = cli === "codex"
+        ? countCodexSessions(root, discovery.codexHome ?? join(homedir(), ".codex"))
+        : countSessions(root, discovery.claudeHome ?? join(homedir(), ".claude"));
+    const relatedIds = new Set();
+    for (const binding of discovery.bindings ?? externalAgentSessionStore.list()) {
+        if (binding.cli !== cli || !isRelatedBinding(binding, root))
+            continue;
+        if (resolve(binding.cwd) !== root)
+            relatedIds.add(binding.sessionId);
+    }
+    return exact + relatedIds.size;
+}
+function isRelatedBinding(binding, root) {
+    return [binding.cwd, binding.workspaceRoot, binding.worktreePath]
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .some((value) => resolve(value) === root);
+}

package/dist/cc-orchestrator/relevance-judge.d.ts

@@ -0,0 +1,16 @@
+/** Scheduling decision for a continued external coding-agent run. */
+export interface JudgeDecision {
+    action: "continue-same" | "continue-fresh" | "stop";
+    handoffSummary?: string;
+    reason: string;
+}
+export interface JudgeInput {
+    goal?: string;
+    lastResult: string;
+    nextPrompt: string;
+}
+/** Injected aux-model call: takes a prompt, returns raw text. */
+export type AuxLlm = (prompt: string) => Promise<string>;
+export declare function buildJudgePrompt(input: JudgeInput): string;
+export declare function parseJudgeResponse(raw: string): JudgeDecision;
+export declare function judgeContinuation(input: JudgeInput, llm: AuxLlm): Promise<JudgeDecision>;

package/dist/cc-orchestrator/relevance-judge.js

@@ -0,0 +1,38 @@
+const SYSTEM = `You decide how a scheduled task loop should continue after one run.
+Reply with ONLY a JSON object: {"action": "continue-same"|"continue-fresh"|"stop", "handoffSummary"?: string, "reason": string}.
+- "stop": the goal is met; no more runs needed.
+- "continue-same": next run should resume the SAME session (work is related, keep context).
+- "continue-fresh": next run should start a FRESH session because the next step is unrelated to what was just done; put a short context summary in handoffSummary.`;
+export function buildJudgePrompt(input) {
+    return [
+        SYSTEM,
+        input.goal ? `\nOverall goal: ${input.goal}` : "",
+        `\nWhat the last run produced:\n${input.lastResult.slice(0, 4000)}`,
+        `\nThe next scheduled prompt:\n${input.nextPrompt}`,
+        `\nDecision JSON:`,
+    ].join("\n");
+}
+export function parseJudgeResponse(raw) {
+    try {
+        const m = raw.match(/\{[\s\S]*\}/);
+        const d = JSON.parse(m ? m[0] : raw);
+        if (d.action === "stop" || d.action === "continue-fresh" || d.action === "continue-same") {
+            return {
+                action: d.action,
+                handoffSummary: typeof d.handoffSummary === "string" ? d.handoffSummary : undefined,
+                reason: typeof d.reason === "string" ? d.reason : "",
+            };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return {
+        action: "continue-same",
+        reason: "unparseable judge output; defaulting to continue-same",
+    };
+}
+export async function judgeContinuation(input, llm) {
+    const raw = await llm(buildJudgePrompt(input));
+    return parseJudgeResponse(raw);
+}