@scotthuang/agent-knock-knock 0.12.12 → 0.12.13

package/dist/src/terminal-list-cli-adapter.js

@@ -11,6 +11,7 @@ import { projectSessionSelectorCandidate } from "./terminal-selector-projection-
 import { listManagedSessions, loadNativeThreadTransition, nativeThreadTransitionsDir, tryLoadManagedSession } from "./session-store.js";
 import { defaultStoreDir, ensureStoreWritable, inspectStoreCompatibility, listConversations, STORE_SESSION_AUTHORITY_PROTOCOL } from "./store.js";
 import { exactCodexReadyStyledComposerCapture } from "./terminal-agent-bridge.js";
+import { captureCodexHumanStartedActiveTaskAnchor } from "./terminal-submission-acceptance.js";
 import { applySessionAuthorityToDispatch, authoritativeTerminalIdentity, compareManagedConversationRecency, decideManagedTerminalAssociation, decideLocalTerminalDispatchOwnership, decideTerminalSendAuthority, decideTerminalSessionAuthorityConflict, managedTurnNeedsAttention as terminalManagedTurnNeedsAttention, nonOwnerTerminalActions, projectBlockingTurn, projectHandoffDecision, projectHandoffPresentation, projectPublicManagementConflict, projectReconcileBindingAction, projectTerminalDispatchConflict, projectTerminalManagement, selectManagedTerminalHistory, selectTerminalAvailableActions } from "./terminal-action-projection.js";
 import { childProcessIdsForRoot, decideManagedBindingConflict, deferredCodexForegroundBindingToken, exactBoundCodexSendSource, isCompleteNativeRollout, nativeAgentIdentityMatchesTurn, processIncarnationRelationship, selectRootTerminalProcesses, terminalControlAliasMatches, terminalControlsShareIncarnation, verifiedEmptyCodexHandoffToken } from "./terminal-authority-policy.js";
 import { decideTerminalBindingMatch, terminalObservationFromListEntry } from "./terminal-binding-authority.js";
@@ -46,6 +47,7 @@ export function createTerminalListCliFacade(dependencies) {
     return {
         runList: (options) => call(() => runList(options)),
         buildTerminalListGroup: (request) => call(() => buildTerminalListGroup(request)),
+        observeExactTerminal: (request) => call(() => observeExactTerminal(request)),
         provisionalManagedBindingTurnCount: (storeDir, session) => call(() => provisionalManagedBindingTurnCount(storeDir, session)),
         managedSessionHasUnresolvedNativeTransition: (storeDir, session) => call(() => managedSessionHasUnresolvedNativeTransition(storeDir, session)),
         managedSessionHasAnyNativeTransition: (storeDir, session) => call(() => managedSessionHasAnyNativeTransition(storeDir, session)),
@@ -70,56 +72,149 @@ async function runList(options) {
             status: "disabled",
             reason: "standalone list is read-only unless --reconcile is supplied"
         };
-    const includeAll = Boolean(options.all);
     const agentFilter = options.agent ? resolveExecutor({ kind: options.agent }).kind : undefined;
     const statusFilter = options.status;
-    const allStoredConversations = listConversations(storeDir);
-    const allManagedConversations = allStoredConversations
+    const terminalScan = await buildTerminalListGroup({ options, agentFilter, statusFilter });
+    const projected = projectTerminalListScan({
+        options,
+        storeDir,
+        store,
+        terminalScan,
+        agentFilter,
+        statusFilter
+    });
+    printJson({
+        store_dir: storeDir,
+        store,
+        reconciliation,
+        action_contracts: listActionContracts(),
+        terminals: projected.terminals,
+        terminal_watches: projected.terminalWatches,
+        unavailable_managed_turns: projected.unavailableManagedTurns,
+        terminal_scan: {
+            ...terminalScan.summary,
+            terminal_count: projected.terminals.length
+        }
+    });
+    runtimeLog("info", "terminals_listed", {
+        store_dir: storeDir,
+        terminal_count: projected.terminals.length,
+        unavailable_managed_turn_count: projected.unavailableManagedTurns.length,
+        terminal_scan_error: terminalScan.summary.error,
+        include_all: projected.includeAll,
+        agent_filter: agentFilter,
+        status_filter: statusFilter,
+        reconciliation
+    });
+}
+function projectTerminalListScan(input) {
+    const { options, storeDir, store, terminalScan, agentFilter, statusFilter, tolerateInvalidWatchRecords } = input;
+    const includeAll = Boolean(options.all);
+    const allManagedConversations = listConversations(storeDir)
         .filter(terminalListRuntime().isDiscoverableTmuxConversation);
     const managedSessions = store.readable
         ? listManagedSessions(storeDir)
         : [];
-    const storedConversations = allManagedConversations
+    const displayedConversations = allManagedConversations
         .filter((conversation) => includeAll || terminalListRuntime().isActiveStatus(conversation.status))
         .filter((conversation) => terminalListRuntime().matchesConfiguredWorkspace(options.workspace, conversation.workspace))
         .filter((conversation) => !agentFilter || executorForConversation(conversation).kind === agentFilter)
         .filter((conversation) => !statusFilter || conversation.status === statusFilter);
-    const terminalScan = await buildTerminalListGroup({ options, agentFilter, statusFilter });
+    const workspaceConversations = allManagedConversations.filter((conversation) => terminalListRuntime().matchesConfiguredWorkspace(options.workspace, conversation.workspace));
     const physicalTerminals = terminalScan.terminalControlled.filter((entry) => terminalListRuntime().matchesConfiguredWorkspace(options.workspace, entry.workspace ?? entry.cwd));
     const projection = terminalFirstListProjection({
         storeDir,
         terminals: physicalTerminals,
         managedSessions,
         sessionAuthorityRequired: Number(store.writer_protocol) >= STORE_SESSION_AUTHORITY_PROTOCOL,
-        allConversations: allManagedConversations.filter((conversation) => terminalListRuntime().matchesConfiguredWorkspace(options.workspace, conversation.workspace)),
-        displayedConversations: storedConversations,
+        allConversations: workspaceConversations,
+        displayedConversations,
         includeAll,
         managedOnly: options.managedOnly === true,
         statusFilter,
         mutationsAllowed: store.writable === true
     });
-    printJson({
-        store_dir: storeDir,
+    const exactWatchScan = terminalListRuntime()
+        .scanTerminalWatchesForExactObservation;
+    const watchObservation = tolerateInvalidWatchRecords && exactWatchScan
+        ? exactWatchScan(storeDir, { includeAll })
+        : {
+            watches: terminalListRuntime().listTerminalWatches?.(storeDir, { includeAll }) ?? [],
+            activeOverlayTrusted: true
+        };
+    const observedTerminalWatches = watchObservation.watches;
+    const terminalWatches = options.managedOnly
+        ? []
+        : observedTerminalWatches
+            .filter((watch) => !agentFilter || watch.agent === agentFilter)
+            .filter((watch) => terminalListRuntime().matchesConfiguredWorkspace(options.workspace, watch.workspace))
+            .filter((watch) => !statusFilter || watch.status === statusFilter);
+    const activeWatchedTerminals = new Set(observedTerminalWatches
+        .filter((watch) => watch.status === "active")
+        .map((watch) => stringValue(watch.terminal_id))
+        .filter((terminalId) => terminalId !== undefined));
+    const terminals = projection.terminals.map((terminal) => !watchObservation.activeOverlayTrusted ||
+        activeWatchedTerminals.has(stringValue(terminal.id) ?? "")
+        ? withoutTerminalWatchAuthority(terminal)
+        : terminal);
+    return {
+        includeAll,
+        terminals,
+        terminalWatches,
+        unavailableManagedTurns: projection.unavailableManagedTurns
+    };
+}
+async function observeExactTerminal(request) {
+    const { options, terminalId } = request;
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(cliCwd()));
+    const store = inspectStoreCompatibility(storeDir);
+    const scan = await buildTerminalListGroup({ options, terminalId });
+    const matches = scan.terminalControlled.filter((terminal) => stringValue(terminal.id) === terminalId);
+    if (matches.length !== 1) {
+        return scan.summary.error
+            ? {
+                state: "unavailable",
+                reason: scan.summary.error,
+                summary: scan.summary
+            }
+            : { state: "absent", summary: scan.summary };
+    }
+    const projected = projectTerminalListScan({
+        options,
+        storeDir,
         store,
-        reconciliation,
-        action_contracts: listActionContracts(),
-        terminals: projection.terminals,
-        unavailable_managed_turns: projection.unavailableManagedTurns,
-        terminal_scan: {
-            ...terminalScan.summary,
-            terminal_count: projection.terminals.length
-        }
-    });
-    runtimeLog("info", "terminals_listed", {
-        store_dir: storeDir,
-        terminal_count: projection.terminals.length,
-        unavailable_managed_turn_count: projection.unavailableManagedTurns.length,
-        terminal_scan_error: terminalScan.summary.error,
-        include_all: includeAll,
-        agent_filter: agentFilter,
-        status_filter: statusFilter,
-        reconciliation
+        terminalScan: scan,
+        tolerateInvalidWatchRecords: true
     });
+    const projectedMatches = projected.terminals.filter((terminal) => stringValue(terminal.id) === terminalId);
+    if (projectedMatches.length !== 1) {
+        return {
+            state: "unavailable",
+            reason: "the exact terminal could not be projected authoritatively",
+            summary: scan.summary
+        };
+    }
+    return {
+        state: "available",
+        rawTerminal: matches[0],
+        terminal: projectedMatches[0],
+        summary: scan.summary
+    };
+}
+function withoutAvailableAction(terminal, action) {
+    if (!isRecord(terminal.available_actions))
+        return terminal;
+    const actions = { ...terminal.available_actions };
+    delete actions[action];
+    return { ...terminal, available_actions: actions };
+}
+function withoutTerminalWatchAuthority(terminal) {
+    const projected = withoutAvailableAction(terminal, "watch");
+    if (!Object.hasOwn(projected, "terminal_watch_hint"))
+        return projected;
+    const safe = { ...projected };
+    delete safe.terminal_watch_hint;
+    return safe;
 }
 async function reconcileStoreForList(storeDir, options) {
     try {
@@ -157,7 +252,7 @@ async function reconcileStoreForList(storeDir, options) {
         idle_timeout_minutes: idle.idle_timeout_minutes
     };
 }
-async function buildTerminalListGroup({ options, agentFilter, statusFilter }) {
+async function buildTerminalListGroup({ options, agentFilter, statusFilter, terminalId }) {
     const empty = {
         terminalControlled: [],
         summary: {
@@ -198,8 +293,17 @@ async function buildTerminalListGroup({ options, agentFilter, statusFilter }) {
         const rootSessions = selectRootTerminalProcesses(activeSessions);
         const controlledSessions = rootSessions.filter((session) => session.terminalControl !== undefined);
         activeCount = controlledSessions.length;
-        for (const session of controlledSessions) {
-            terminalControlled.push(await terminalControlledListEntry(session, activeSessions, options, bridge));
+        const selectedSessions = terminalId
+            ? controlledSessions.filter((session) => bridge.terminalConversationId(session) === terminalId)
+            : controlledSessions;
+        for (const session of selectedSessions) {
+            try {
+                terminalControlled.push(await terminalControlledListEntry(session, activeSessions, options, bridge));
+            }
+            catch (error) {
+                errors.push(`terminal process ${session.pid}: ` +
+                    (error instanceof Error ? error.message : String(error)));
+            }
         }
     }
     catch (error) {
@@ -272,17 +376,28 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         terminalTarget: terminalControl.target
     });
     const { orphanedDispatch, nativeIdentityObservation, nativeAgentIdentity, codexOpenRootRolloutInventory, nativeProcessUuid, nativeProcessBirth, nativeProcessEvidence } = await observeTerminalNativeListIdentity(session, terminalControl, options, bridge);
+    const effectiveTerminalState = effectiveTerminalListState({
+        session,
+        terminalState,
+        nativeIdentityObservation,
+        nativeAgentIdentity,
+        nativeProcessUuid,
+        nativeProcessBirth
+    });
+    const terminalStatusSnapshot = effectiveTerminalState._terminal_status_snapshot
+        ? terminalBridgeStatusWithActivity(effectiveTerminalState._terminal_status_snapshot, effectiveTerminalState.activity_state, effectiveTerminalState.activity_reason)
+        : undefined;
     const statusCardObservation = session.agent === "codex" &&
-        typeof terminalState.screen_excerpt === "string"
+        typeof effectiveTerminalState.screen_excerpt === "string"
         ? bridge.registry.require("codex").observeThreadLifecycle?.({
             operation: { kind: "new_thread" },
             phase: "before",
-            screen: terminalState.screen_excerpt
+            screen: effectiveTerminalState.screen_excerpt
         })
         : undefined;
     const statusCardNativeThreadId = statusCardObservation?.status === "observed" &&
-        terminalState.activity_state === "idle" &&
-        terminalState.approval_state.blocked !== true &&
+        effectiveTerminalState.activity_state === "idle" &&
+        effectiveTerminalState.approval_state.blocked !== true &&
         isExactNativeThreadId(statusCardObservation.nativeThreadId)
         ? statusCardObservation.nativeThreadId
         : undefined;
@@ -304,7 +419,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     };
     const codexLatentClearResumeObservationValue = session.agent === "codex"
         ? terminalListRuntime().codexLatentClearResumeObservation({
-            screen: terminalState.screen_excerpt,
+            screen: effectiveTerminalState.screen_excerpt,
             agentVersion
         })
         : undefined;
@@ -325,7 +440,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     const automatedInputComposerReady = await observeAutomatedInputComposerReady({
         session,
         terminalControl,
-        terminalState,
+        terminalState: effectiveTerminalState,
         nativeIdentityObservation,
         codexOpenRootRolloutInventory,
         options
@@ -363,9 +478,15 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         confidence: session.confidence,
         reason: session.reason,
         terminal_control: terminalControl,
-        approval_state: terminalState.approval_state,
-        activity_state: terminalState.activity_state,
-        activity_reason: terminalState.activity_reason,
+        approval_state: effectiveTerminalState.approval_state,
+        activity_state: effectiveTerminalState.activity_state,
+        activity_reason: effectiveTerminalState.activity_reason,
+        // Internal exact-observation evidence. The public projection strips this
+        // object; raw terminal status reuses it so screen, approval, and activity
+        // all describe the same capture.
+        ...(terminalStatusSnapshot
+            ? { _terminal_status_snapshot: terminalStatusSnapshot }
+            : {}),
         // Internal action-projection evidence. terminalFirstListProjection strips
         // this field after gating every automated-input action that can follow a
         // human native-thread switch.
@@ -398,33 +519,20 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
                 }
             }
             : {}),
-        commands: {
-            send: !terminalHasBlockingTurn,
-            approve: terminalControl.capabilities.includes("terminal_approval") &&
-                terminalState.approval_state.approvable === true,
-            status: true,
-            cancel: terminalControl.capabilities.includes("terminal_cancel"),
-            close: orphanedDispatch !== undefined,
-            new_thread: lifecycleCapability.status === "supported" &&
-                lifecycleCapability.newThread === true &&
-                codexLifecycleIncarnationAvailable &&
-                !terminalHasBlockingTurn,
-            list_resumable_threads: lifecycleCapability.status === "supported" &&
-                lifecycleCapability.resumeExact === true &&
-                codexLifecycleIncarnationAvailable,
-            native_inspect: nativeInspectionCapability.status === "supported" &&
-                nativeInspectionCapability.statusInspection === true &&
-                terminalState.activity_state === "idle" &&
-                automatedInputComposerReady &&
-                terminalControl.capabilities.includes("send_keys") &&
-                terminalControl.capabilities.includes("screen_status") &&
-                (session.agent === "codex"
-                    ? codexLifecycleIncarnationAvailable
-                    : Boolean(nativeAgentIdentity?.sessionId &&
-                        nativeAgentIdentity.processUuid)) &&
-                orphanedDispatch === undefined &&
-                !terminalHasBlockingTurn
-        }
+        commands: terminalListCommands({
+            agent: session.agent,
+            terminalControl,
+            terminalState: effectiveTerminalState,
+            lifecycleCapability,
+            nativeInspectionCapability,
+            nativeAgentIdentity,
+            nativeProcessUuid,
+            nativeProcessBirth,
+            codexLifecycleIncarnationAvailable,
+            automatedInputComposerReady,
+            hasOrphanedDispatch: orphanedDispatch !== undefined,
+            terminalHasBlockingTurn
+        })
     };
     const availableActions = renderAvailableListActions(entry);
     const { commands: _commands, ...publicEntry } = entry;
@@ -433,6 +541,115 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         available_actions: availableActions
     };
 }
+function terminalListCommands(input) {
+    const { agent, terminalControl, terminalState, lifecycleCapability, nativeInspectionCapability, nativeAgentIdentity, nativeProcessUuid, nativeProcessBirth, codexLifecycleIncarnationAvailable, automatedInputComposerReady, hasOrphanedDispatch, terminalHasBlockingTurn } = input;
+    return {
+        send: !terminalHasBlockingTurn,
+        approve: terminalControl.capabilities.includes("terminal_approval") &&
+            terminalState.approval_state.approvable === true,
+        status: true,
+        cancel: terminalControl.capabilities.includes("terminal_cancel"),
+        close: hasOrphanedDispatch,
+        new_thread: lifecycleCapability.status === "supported" &&
+            lifecycleCapability.newThread === true &&
+            codexLifecycleIncarnationAvailable &&
+            !terminalHasBlockingTurn,
+        list_resumable_threads: lifecycleCapability.status === "supported" &&
+            lifecycleCapability.resumeExact === true &&
+            codexLifecycleIncarnationAvailable,
+        native_inspect: nativeInspectionCapability.status === "supported" &&
+            nativeInspectionCapability.statusInspection === true &&
+            terminalState.activity_state === "idle" &&
+            automatedInputComposerReady &&
+            terminalControl.capabilities.includes("send_keys") &&
+            terminalControl.capabilities.includes("screen_status") &&
+            (agent === "codex"
+                ? codexLifecycleIncarnationAvailable
+                : Boolean(nativeAgentIdentity?.sessionId &&
+                    nativeAgentIdentity.processUuid)) &&
+            !hasOrphanedDispatch &&
+            !terminalHasBlockingTurn,
+        watch: lifecycleCapability.status === "supported" &&
+            (terminalState.activity_state === "working" ||
+                terminalState.activity_state === "awaiting_approval") &&
+            Boolean(nativeAgentIdentity?.sessionId) &&
+            (agent !== "codex" || Boolean(nativeAgentIdentity?.rollout)) &&
+            Boolean(nativeProcessUuid) &&
+            Boolean(nativeProcessBirth) &&
+            !hasOrphanedDispatch &&
+            !terminalHasBlockingTurn
+    };
+}
+function effectiveTerminalListState(input) {
+    const { session, terminalState, nativeIdentityObservation, nativeAgentIdentity, nativeProcessUuid, nativeProcessBirth } = input;
+    if (session.agent !== "codex" ||
+        terminalState.activity_state === "working" ||
+        terminalState.activity_state === "awaiting_approval" ||
+        terminalState.approval_state.blocked === true) {
+        return terminalState;
+    }
+    if (nativeIdentityObservation.status === "verified_absent") {
+        return terminalState;
+    }
+    if (nativeIdentityObservation.status !== "resolved" ||
+        !nativeAgentIdentity?.rollout ||
+        !nativeAgentIdentity.sessionId ||
+        !nativeProcessUuid ||
+        !nativeProcessBirth) {
+        return terminalListStateWithUnavailableDurableActivity(terminalState, nativeIdentityObservation.status === "unavailable"
+            ? nativeIdentityObservation.reason ??
+                "exact Codex identity observation failed"
+            : "exact Codex rollout/process identity is incomplete");
+    }
+    const currentIdentity = {
+        sessionId: nativeAgentIdentity.sessionId,
+        processUuid: nativeProcessUuid,
+        processBirth: nativeProcessBirth,
+        rollout: nativeAgentIdentity.rollout
+    };
+    try {
+        if (!captureCodexHumanStartedActiveTaskAnchor({ currentIdentity })) {
+            return terminalState;
+        }
+        return {
+            ...terminalState,
+            activity_state: "working",
+            activity_reason: "Codex rollout contains an exact unfinished human-started task"
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        runtimeLog("warn", "terminal_durable_activity_unavailable", {
+            agent: session.agent,
+            pid: session.pid,
+            reason
+        });
+        return terminalListStateWithUnavailableDurableActivity(terminalState, reason);
+    }
+}
+function terminalListStateWithUnavailableDurableActivity(terminalState, reason) {
+    return {
+        ...terminalState,
+        activity_state: "unknown",
+        activity_reason: `durable Codex activity evidence is unavailable: ${reason}`
+    };
+}
+function terminalBridgeStatusWithActivity(status, activityState, activityReason) {
+    const descriptors = Object.getOwnPropertyDescriptors(status);
+    descriptors.activity_state = {
+        configurable: true,
+        enumerable: true,
+        value: activityState,
+        writable: true
+    };
+    descriptors.activity_reason = {
+        configurable: true,
+        enumerable: true,
+        value: activityReason,
+        writable: true
+    };
+    return Object.create(Object.getPrototypeOf(status), descriptors);
+}
 async function observeTerminalNativeListIdentity(session, terminalControl, options, bridge) {
     const orphanedDispatch = terminalListRuntime().orphanedTerminalDispatchForRecovery(terminalControl);
     let codexIdentityContext;
@@ -562,7 +779,7 @@ async function observeAutomatedInputComposerReady({ session, terminalControl, te
 }
 function observeTerminalListBindingAuthority(terminal, context) {
     const { storeDir, managedSessions, allConversations, displayedConversations, mutationsAllowed, nonterminalDeferredTransfers } = context;
-    const { _automated_input_composer_ready: automatedInputComposerReady, _codex_open_root_rollout_inventory: codexOpenRootRolloutInventoryValue, _codex_latent_clear_resume: codexLatentClearResumeValue, ...publicTerminal } = terminal;
+    const { _automated_input_composer_ready: automatedInputComposerReady, _codex_open_root_rollout_inventory: codexOpenRootRolloutInventoryValue, _codex_latent_clear_resume: codexLatentClearResumeValue, _terminal_status_snapshot: _terminalStatusSnapshot, ...publicTerminal } = terminal;
     const codexOpenRootRolloutInventory = isRecord(codexOpenRootRolloutInventoryValue)
         ? codexOpenRootRolloutInventoryValue
         : undefined;
@@ -1995,6 +2212,7 @@ async function listStateForTerminal(agent, terminalControl, options, bridge = te
             activity_state: status.activity_state,
             activity_reason: status.activity_reason,
             capability_limitation: status.capability_limitation,
+            _terminal_status_snapshot: status,
             // Internal projection evidence; terminalControlledListEntry selects all
             // public fields explicitly and never exposes the pane excerpt itself.
             screen_excerpt: status.screen.excerpt