pulseed 0.6.5 → 0.6.6

package/dist/runtime/control/runtime-control-service.js

@@ -2,34 +2,60 @@ import { randomUUID } from "node:crypto";
 import { createRuntimeSessionRegistry, } from "../session-registry/index.js";
 import { RuntimeEvidenceLedger } from "../store/evidence-ledger.js";
 import { RuntimeOperationStore } from "../store/runtime-operation-store.js";
+import { AttentionStateStore } from "../store/attention-state-store.js";
 import { RuntimeOperatorHandoffStore } from "../store/operator-handoff-store.js";
 import { BrowserSessionStore, RuntimeAuthHandoffStore } from "../interactive-automation/index.js";
 import { breakerKey, GuardrailStore } from "../guardrails/index.js";
+import { assembleCompanionStateReducerInput, deriveRuntimeItemControlPolicy, deriveCompanionStateSnapshot, } from "../companion-state-reducer.js";
+import { buildRuntimeEventHighWatermark, runtimeItemFromAuthHandoff, runtimeItemFromBackgroundRun, runtimeItemFromBrowserSession, runtimeItemFromGuardrailBreaker, runtimeItemsFromBackpressureSnapshot, } from "../store/runtime-operation-companion.js";
 import { resolveRuntimeTarget } from "./runtime-target-resolver.js";
+import { actorKey, formatPermissionGrantAudit, formatPermissionGrantSummary, hasPermissionGrantSelectionContext, nextPermissionCapabilities, permissionGrantMatchesRequest, replacementGrantInput, } from "./runtime-control-permission-grants.js";
+const DEACTIVATES_COMPANION_CONTROL = {
+    leave_quiet_mode: "enter_quiet_mode",
+    resume_proactivity: "pause_proactivity",
+    resume_companion: "suspend_companion",
+};
 export class RuntimeControlService {
     operationStore;
     sessionRegistry;
     evidenceLedger;
     operatorHandoffStore;
+    permissionGrantStore;
     authHandoffStore;
     browserSessionStore;
     guardrailStore;
+    attentionStore;
     executor;
     now;
     constructor(options = {}) {
-        this.operationStore = options.operationStore ?? new RuntimeOperationStore(options.runtimeRoot);
+        const runtimeRoot = options.runtimeRoot ?? options.operationStore?.runtimeRootDir();
+        const controlDbOptions = options.stateManager
+            ? { controlBaseDir: options.stateManager.getBaseDir() }
+            : options.operationStore?.runtimeControlDbOptions();
+        this.operationStore = options.operationStore ?? new RuntimeOperationStore(runtimeRoot, controlDbOptions);
         this.sessionRegistry = options.sessionRegistry ?? (options.stateManager
             ? createRuntimeSessionRegistry({ stateManager: options.stateManager })
             : undefined);
-        this.evidenceLedger = options.evidenceLedger ?? (options.runtimeRoot ? new RuntimeEvidenceLedger(options.runtimeRoot) : undefined);
-        this.operatorHandoffStore = options.operatorHandoffStore ?? (options.runtimeRoot ? new RuntimeOperatorHandoffStore(options.runtimeRoot) : undefined);
-        this.authHandoffStore = options.authHandoffStore ?? new RuntimeAuthHandoffStore(options.runtimeRoot);
-        this.browserSessionStore = options.browserSessionStore ?? new BrowserSessionStore(options.runtimeRoot);
-        this.guardrailStore = options.guardrailStore ?? new GuardrailStore(options.runtimeRoot);
+        this.evidenceLedger = options.evidenceLedger ?? (runtimeRoot ? new RuntimeEvidenceLedger(runtimeRoot) : undefined);
+        this.operatorHandoffStore = options.operatorHandoffStore ?? (runtimeRoot ? new RuntimeOperatorHandoffStore(runtimeRoot, controlDbOptions) : undefined);
+        this.permissionGrantStore = options.permissionGrantStore;
+        this.authHandoffStore = options.authHandoffStore ?? new RuntimeAuthHandoffStore(runtimeRoot, controlDbOptions);
+        this.browserSessionStore = options.browserSessionStore ?? new BrowserSessionStore(runtimeRoot, controlDbOptions);
+        this.guardrailStore = options.guardrailStore ?? new GuardrailStore(runtimeRoot, controlDbOptions);
+        this.attentionStore = options.attentionStore ?? (runtimeRoot ? new AttentionStateStore(runtimeRoot, controlDbOptions) : undefined);
         this.executor = options.executor;
         this.now = options.now ?? (() => new Date());
     }
     async request(request) {
+        if (isCompanionWideControlKind(request.intent.kind)) {
+            return this.handleCompanionWideControl(request);
+        }
+        if (isSessionControlKind(request.intent.kind)) {
+            return this.handleSessionControl(request);
+        }
+        if (isPermissionControlKind(request.intent.kind)) {
+            return this.handlePermissionControl(request);
+        }
         if (isRunControlKind(request.intent.kind)) {
             return this.handleRunControl(request);
         }
@@ -85,6 +111,396 @@ export class RuntimeControlService {
         const result = await this.applyAutomationControl(request);
         return this.recordAutomationOperation(request, result.success ? "verified" : "blocked", result.success, result.message);
     }
+    async assembleCompanionStateInput(request = {}) {
+        const currentTime = request.currentTime ?? this.nowIso();
+        const collectedRuntimeItems = await this.collectRuntimeItems(currentTime);
+        const runtimeEvents = await this.operationStore.listRuntimeEvents();
+        const projectedControls = request.globalControls
+            ? null
+            : await this.projectGlobalControlState(collectedRuntimeItems);
+        const globalControls = request.globalControls ?? projectedControls?.controls ?? [];
+        const activeControls = request.globalControls
+            ? globalControls.filter((entry) => entry.state === "active").map((entry) => entry.control)
+            : projectedControls?.activeControls ?? [];
+        const runtimeItems = applyCompanionControlState(collectedRuntimeItems, globalControls, activeControls);
+        return assembleCompanionStateReducerInput({
+            runtime_items: runtimeItems,
+            recent_runtime_events: runtimeEvents,
+            active_surface_ref: request.activeSurfaceRef ?? null,
+            surface_invalidation_events: request.surfaceInvalidationEvents ?? [],
+            global_control_state_ref: request.globalControlStateRef ?? projectedControls?.stateRef ?? null,
+            global_controls: globalControls,
+            control_overlays: request.controlOverlays ?? [],
+            pre_suspend_mode: request.preSuspendMode ?? null,
+            user_activity_refs: request.userActivityRefs ?? [],
+            feedback_refs: request.feedbackRefs ?? [],
+            safety_context_refs: request.safetyContextRefs ?? [],
+            event_high_watermark: request.eventHighWatermark
+                ?? buildRuntimeEventHighWatermark(runtimeEvents, `runtime-event-high-watermark:${currentTime}`),
+            current_time: currentTime,
+        });
+    }
+    async recomputeCompanionState(request = {}) {
+        const input = await this.assembleCompanionStateInput(request);
+        return {
+            input,
+            snapshot: deriveCompanionStateSnapshot(input),
+        };
+    }
+    inspectCompanionState(request) {
+        return this.request({ ...request, intent: { kind: "inspect_companion_state", reason: request.reason } });
+    }
+    setCompanionControl(request) {
+        return this.request({ ...request, intent: { kind: request.control, reason: request.reason } });
+    }
+    inspectSession(request) {
+        return this.request({ ...request, intent: { kind: "inspect_session", reason: request.reason, target: targetFromRunRequest(request) } });
+    }
+    summarizeSessionWithoutResuming(request) {
+        return this.request({
+            ...request,
+            intent: { kind: "summarize_session_without_resuming", reason: request.reason, target: targetFromRunRequest(request) },
+        });
+    }
+    async handleCompanionWideControl(request) {
+        const runtimeItemsBeforeControl = await this.collectRuntimeItems(this.nowIso());
+        const initial = await this.createInitialOperation(request);
+        const control = request.intent.kind;
+        const affectedRefs = affectedRuntimeRefsForControl(control, runtimeItemsBeforeControl);
+        if (request.intent.kind === "inspect_companion_state") {
+            const current = await this.recomputeCompanionState({
+                activeSurfaceRef: null,
+                currentTime: this.nowIso(),
+            });
+            const inspection = buildCompanionStateInspection(current.input.runtime_items, current.snapshot);
+            const inspected = await this.update(initial, "verified", {
+                ok: true,
+                message: formatCompanionStateSummary(current.snapshot, inspection),
+                companionStateInspection: inspection,
+            });
+            return this.toResult(inspected);
+        }
+        const quietWorkStop = control === "stop_all_quiet_work"
+            ? await this.stopActiveQuietWork(initial, runtimeItemsBeforeControl, request)
+            : null;
+        const agendaSuppression = isDurableAgendaSuppressionControl(control) && this.attentionStore
+            ? await this.attentionStore.suppressAgendaForControl({
+                control,
+                reason: request.intent.reason,
+                now: this.nowIso(),
+                auditRef: { kind: "audit_trace", id: `runtime-control-operation:${initial.operation_id}` },
+            })
+            : null;
+        const verified = await this.update(initial, "verified", {
+            ok: quietWorkStop?.ok ?? true,
+            message: [
+                formatCompanionControlApplied(control, affectedRefs),
+                quietWorkStop?.message,
+                agendaSuppression && agendaSuppression.suppressed_count > 0
+                    ? `Durable attention agenda suppressed ${agendaSuppression.suppressed_count} item(s); held items will not flush automatically.`
+                    : null,
+            ].filter((part) => Boolean(part)).join(" "),
+            affectedRuntimeRefs: affectedRefs,
+        });
+        return this.toResult(verified);
+    }
+    async stopActiveQuietWork(parentOperation, runtimeItems, request) {
+        const quietItems = runtimeItems
+            .filter(activeRuntimeItem)
+            .filter(quietWorkRuntimeItem);
+        if (quietItems.length === 0) {
+            return {
+                ok: true,
+                message: "No active quiet work needed an interruption request.",
+                results: [],
+            };
+        }
+        const results = [];
+        for (const item of quietItems) {
+            results.push(await this.stopQuietWorkItem(parentOperation, item, request));
+        }
+        const sentCount = results.filter((result) => result.ok).length;
+        const nonExecutionCount = results.filter((result) => !result.ok).length;
+        const pieces = [
+            sentCount > 0 ? `Typed pause request sent for ${sentCount} active quiet run(s).` : null,
+            nonExecutionCount > 0 ? `${nonExecutionCount} affected quiet item(s) recorded typed non-execution state.` : null,
+        ].filter((piece) => Boolean(piece));
+        return {
+            ok: nonExecutionCount === 0,
+            message: pieces.join(" "),
+            results,
+        };
+    }
+    async stopQuietWorkItem(parentOperation, item, request) {
+        let operation = await this.createQuietWorkPauseOperation(parentOperation, item, request);
+        if (!operation.target?.run_id || !operation.target.goal_id) {
+            operation = await this.update(operation, "blocked", {
+                ok: false,
+                message: `Quiet-work item ${item.item_id} was held but not paused because it has no typed goal/runtime bridge.`,
+            });
+            await this.appendControlEvidence(operation);
+            return quietWorkStopResult(item.item_id, operation);
+        }
+        const approved = await this.approveIfRequired(operation, request.approvalFn);
+        if (!approved.ok) {
+            const saved = approved.result.operationId
+                ? await this.operationStore.load(approved.result.operationId)
+                : null;
+            operation = saved ?? operation;
+            await this.appendControlEvidence(operation);
+            return quietWorkStopResult(item.item_id, operation);
+        }
+        // The parent companion-wide control is the explicit user command; these child
+        // operations still pass the normal pause_run approval gate before daemon I/O.
+        operation = approved.operation;
+        if (!this.executor) {
+            const runId = operation.target?.run_id ?? item.item_id;
+            operation = await this.update(operation, "blocked", {
+                ok: false,
+                message: `Quiet-work run ${runId} was held but not paused because no runtime control executor is configured.`,
+            });
+            await this.appendControlEvidence(operation);
+            return quietWorkStopResult(item.item_id, operation);
+        }
+        const acknowledged = await this.acknowledge(operation);
+        const executed = await this.executeAcknowledgedOperation(acknowledged, request);
+        const executedOperation = executed.operationId
+            ? await this.operationStore.load(executed.operationId)
+            : null;
+        const saved = executedOperation ?? acknowledged;
+        await this.appendControlEvidence(saved);
+        return quietWorkStopResult(item.item_id, saved);
+    }
+    createQuietWorkPauseOperation(parentOperation, item, request) {
+        const requestedAt = this.nowIso();
+        const target = quietWorkPauseTarget(item);
+        return this.operationStore.save({
+            operation_id: randomUUID(),
+            kind: "pause_run",
+            state: "pending",
+            requested_at: requestedAt,
+            updated_at: requestedAt,
+            requested_by: request.requestedBy ?? { surface: "chat" },
+            reply_target: normalizeReplyTarget(request.replyTarget ?? { surface: "chat" }),
+            reason: `Parent stop_all_quiet_work ${parentOperation.operation_id}: ${request.intent.reason}`,
+            expected_health: expectedHealthFor("pause_run"),
+            ...(target ? { target } : {}),
+        });
+    }
+    async handleSessionControl(request) {
+        const initial = await this.createInitialOperation(request);
+        if (!this.sessionRegistry) {
+            const blocked = await this.update(initial, "blocked", {
+                ok: false,
+                message: "Runtime session catalog is not available for session control.",
+            });
+            return this.toResult(blocked);
+        }
+        const sessionId = request.intent.target?.sessionId;
+        if (!sessionId) {
+            const blocked = await this.update(initial, "blocked", {
+                ok: false,
+                message: `${request.intent.kind} requires an explicit session id; refusing to fall back to latest session.`,
+            });
+            return this.toResult(blocked);
+        }
+        const snapshot = await this.sessionRegistry.snapshot();
+        const session = snapshot.sessions.find((candidate) => candidate.id === sessionId);
+        if (!session) {
+            const blocked = await this.update(initial, "blocked", {
+                ok: false,
+                message: `Runtime session ${sessionId} was not found; refusing to fall back to latest session.`,
+                resumeOutcome: "resume_rejected_stale",
+            });
+            return this.toResult(blocked);
+        }
+        const verified = await this.update(initial, "verified", {
+            ok: true,
+            message: request.intent.kind === "summarize_session_without_resuming"
+                ? formatSessionSummaryOnly(session)
+                : formatSessionInspection(session),
+            resumeOutcome: request.intent.kind === "summarize_session_without_resuming" ? "summary_only" : "inspect_only",
+        });
+        return this.toResult(verified);
+    }
+    async handlePermissionControl(request) {
+        const initial = await this.createInitialOperation(request);
+        if (!this.permissionGrantStore) {
+            const blocked = await this.update(initial, "blocked", {
+                ok: false,
+                message: "PermissionGrant control is unavailable because the permission grant store is not configured.",
+            });
+            return this.toResult(blocked);
+        }
+        switch (request.intent.kind) {
+            case "inspect_permission_boundary": {
+                const grants = await this.matchPermissionGrants(request, { activeOnly: true });
+                const inspected = await this.update(initial, "verified", {
+                    ok: true,
+                    message: formatPermissionGrantSummary(grants),
+                });
+                return this.toResult(inspected);
+            }
+            case "audit_permission_check": {
+                const grants = await this.matchPermissionGrants(request, { activeOnly: false });
+                const audited = await this.update(initial, "verified", {
+                    ok: true,
+                    message: formatPermissionGrantAudit(grants),
+                });
+                return this.toResult(audited);
+            }
+            case "revoke_permission": {
+                const selected = await this.selectSinglePermissionGrant(request);
+                if (!selected.ok) {
+                    const blocked = await this.update(initial, "blocked", { ok: false, message: selected.message });
+                    return this.toResult(blocked);
+                }
+                const revoked = await this.permissionGrantStore.revoke(selected.grant.grant_id, {
+                    revoked_by: actorKey(request.requestedBy),
+                    reason: request.intent.reason,
+                    audit_refs: [`runtime-control:${initial.operation_id}`],
+                });
+                const updated = await this.update(initial, revoked ? "verified" : "blocked", {
+                    ok: Boolean(revoked),
+                    message: revoked
+                        ? `Revoked PermissionGrant ${revoked.grant_id}. Future covered actions will ask again or block according to policy.`
+                        : `PermissionGrant ${selected.grant.grant_id} could not be revoked.`,
+                });
+                return this.toResult(updated);
+            }
+            case "narrow_permission":
+            case "extend_permission": {
+                const selected = await this.selectSinglePermissionGrant(request);
+                if (!selected.ok) {
+                    const blocked = await this.update(initial, "blocked", { ok: false, message: selected.message });
+                    return this.toResult(blocked);
+                }
+                if (request.intent.kind === "extend_permission" && (request.intent.permissionCapabilities?.length ?? 0) === 0) {
+                    const blocked = await this.update(initial, "blocked", {
+                        ok: false,
+                        message: "extend_permission requires at least one explicit grant capability.",
+                    });
+                    return this.toResult(blocked);
+                }
+                const capabilities = nextPermissionCapabilities(selected.grant, request.intent.permissionCapabilities, request.intent.kind);
+                if (capabilities.length === 0) {
+                    const blocked = await this.update(initial, "blocked", {
+                        ok: false,
+                        message: `${request.intent.kind} requires at least one explicit grant capability.`,
+                    });
+                    return this.toResult(blocked);
+                }
+                const approval = request.intent.kind === "extend_permission"
+                    ? await this.approveIfRequired(initial, request.approvalFn)
+                    : { ok: true, operation: initial };
+                if (!approval.ok)
+                    return approval.result;
+                const replacementInput = replacementGrantInput(selected.grant, capabilities, request, approval.operation.operation_id);
+                const superseded = await this.permissionGrantStore.supersede(selected.grant.grant_id, replacementInput, {
+                    audit_refs: [`runtime-control:${approval.operation.operation_id}`],
+                });
+                const activated = superseded
+                    ? await this.permissionGrantStore.activate(superseded.replacement.grant_id, {
+                        audit_refs: [`runtime-control:${approval.operation.operation_id}`],
+                    })
+                    : null;
+                const updated = await this.update(approval.operation, activated ? "verified" : "blocked", {
+                    ok: Boolean(activated),
+                    message: activated
+                        ? `Updated PermissionGrant ${selected.grant.grant_id}; replacement ${activated.grant_id} allows ${activated.capabilities.join(", ")}.`
+                        : `PermissionGrant ${selected.grant.grant_id} could not be updated.`,
+                });
+                return this.toResult(updated);
+            }
+        }
+        const blocked = await this.update(initial, "blocked", {
+            ok: false,
+            message: `Unsupported permission control operation: ${request.intent.kind}`,
+        });
+        return this.toResult(blocked);
+    }
+    async collectRuntimeItems(currentTime) {
+        const items = [
+            ...await this.operationStore.listRuntimeItems(),
+        ];
+        if (this.attentionStore) {
+            items.push(...await this.attentionStore.listRuntimeItems(currentTime));
+        }
+        if (this.sessionRegistry) {
+            const snapshot = await this.sessionRegistry.snapshot();
+            items.push(...snapshot.background_runs.map((run) => runtimeItemFromBackgroundRun(run, currentTime)));
+        }
+        items.push(...(await this.authHandoffStore.list()).map((handoff) => runtimeItemFromAuthHandoff(handoff, currentTime)));
+        items.push(...(await this.browserSessionStore.list()).map((session) => runtimeItemFromBrowserSession(session, currentTime)));
+        items.push(...(await this.guardrailStore.listBreakers()).map(runtimeItemFromGuardrailBreaker));
+        const backpressure = await this.guardrailStore.loadBackpressureSnapshot();
+        if (backpressure) {
+            items.push(...runtimeItemsFromBackpressureSnapshot(backpressure, currentTime));
+        }
+        return items;
+    }
+    async projectGlobalControlState(runtimeItems) {
+        const operations = [
+            ...await this.operationStore.listCompleted(),
+            ...await this.operationStore.listPending(),
+        ]
+            .filter((operation) => isCompanionWideControlKind(operation.kind))
+            .filter((operation) => operation.kind !== "inspect_companion_state")
+            .filter((operation) => operation.state === "verified")
+            .sort((left, right) => left.updated_at.localeCompare(right.updated_at));
+        if (operations.length === 0) {
+            return { stateRef: null, controls: [], activeControls: [] };
+        }
+        const byControl = new Map();
+        for (const operation of operations) {
+            const control = operation.kind;
+            const affectedRefs = operation.result?.affected_runtime_refs
+                ?? affectedRuntimeRefsForControl(control, runtimeItems);
+            const deactivated = DEACTIVATES_COMPANION_CONTROL[control];
+            if (deactivated) {
+                const previous = byControl.get(deactivated);
+                const preservedAffectedRefs = uniqueStrings([
+                    ...(previous?.affected_runtime_refs ?? []),
+                    ...affectedRefs,
+                ]);
+                const preservedAuditRefs = uniqueStrings([
+                    ...(previous?.audit_refs ?? []),
+                    `runtime-control-operation:${operation.operation_id}`,
+                ]);
+                byControl.set(deactivated, companionControlEntry({
+                    control: deactivated,
+                    state: "inactive",
+                    operation,
+                    affectedRefs: preservedAffectedRefs,
+                    auditRefs: preservedAuditRefs,
+                }));
+                byControl.set(control, companionControlEntry({
+                    control,
+                    state: "inactive",
+                    operation,
+                    affectedRefs,
+                }));
+                continue;
+            }
+            const existing = byControl.get(control);
+            if (existing?.state === "inactive" && existing.updated_at >= operation.updated_at) {
+                continue;
+            }
+            byControl.set(control, companionControlEntry({
+                control,
+                state: oneShotCompanionControls().has(control) ? "inactive" : "active",
+                operation,
+                affectedRefs,
+            }));
+        }
+        const latest = operations[operations.length - 1];
+        const controls = [...byControl.values()].sort((left, right) => left.updated_at.localeCompare(right.updated_at));
+        return {
+            stateRef: `global-control-state:${latest.operation_id}:${encodeURIComponent(latest.updated_at)}`,
+            controls,
+            activeControls: controls.filter((entry) => entry.state === "active").map((entry) => entry.control),
+        };
+    }
     async handleRunControl(request) {
         const initial = await this.createInitialOperation(request);
         if (initial.state === "blocked")
@@ -106,10 +522,23 @@ export class RuntimeControlService {
             const blocked = await this.update(initial, "blocked", {
                 ok: false,
                 message: `Runtime control ${request.intent.kind} is blocked: selected run ${initial.target?.run_id ?? "unknown"} has no typed goal/runtime bridge yet.`,
+                ...(request.intent.kind === "resume_run" ? { resumeOutcome: "resume_rejected_safety" } : {}),
             });
             await this.appendControlEvidence(blocked);
             return this.toResult(blocked);
         }
+        if (request.intent.kind === "resume_run") {
+            const resumeDecision = await this.decideRunResume(initial);
+            if (resumeDecision.outcome !== "resume_allowed") {
+                const blocked = await this.update(initial, "blocked", {
+                    ok: false,
+                    message: resumeDecision.message,
+                    resumeOutcome: resumeDecision.outcome,
+                });
+                await this.appendControlEvidence(blocked);
+                return this.toResult(blocked);
+            }
+        }
         const approved = await this.approveIfRequired(initial, request.approvalFn);
         if (!approved.ok)
             return approved.result;
@@ -122,6 +551,76 @@ export class RuntimeControlService {
         }
         return result;
     }
+    async decideRunResume(operation) {
+        if (!this.sessionRegistry || !operation.target?.run_id) {
+            return {
+                outcome: "resume_rejected_safety",
+                message: "Resume is blocked because runtime session evidence is unavailable.",
+            };
+        }
+        const snapshot = await this.sessionRegistry.snapshot();
+        const run = snapshot.background_runs.find((candidate) => candidate.id === operation.target?.run_id);
+        if (!run) {
+            return {
+                outcome: "resume_rejected_stale",
+                message: `Runtime run ${operation.target.run_id} was not found; refusing to fall back to latest run.`,
+            };
+        }
+        if (run.status !== "running" && run.status !== "queued") {
+            return {
+                outcome: "resume_requires_regrounding",
+                message: `Runtime run ${run.id} is ${run.status}; resume requires explicit re-grounding or inspect/summary first.`,
+            };
+        }
+        const runtimeItems = await this.collectRuntimeItems(this.nowIso());
+        const projectedControls = await this.projectGlobalControlState(runtimeItems);
+        const controlledItems = applyCompanionControlState(runtimeItems, projectedControls.controls, projectedControls.activeControls);
+        const runtimeItem = controlledItems.find((item) => item.item_id === `background-run:${run.id}`);
+        if (!runtimeItem) {
+            return {
+                outcome: "resume_rejected_stale",
+                message: `Runtime run ${run.id} has no RuntimeItem projection; refusing to fall back to latest run.`,
+            };
+        }
+        if (runtimeItem.control_policy.forbidden_controls.includes("resume_item")) {
+            return resumeBlockedByRuntimeItemPolicy(run.id, runtimeItem);
+        }
+        return {
+            outcome: "resume_allowed",
+            message: `Runtime run ${run.id} is current for resume admission.`,
+        };
+    }
+    async matchPermissionGrants(request, options) {
+        if (!this.permissionGrantStore)
+            return [];
+        const grants = options.activeOnly
+            ? await this.permissionGrantStore.listActive()
+            : await this.permissionGrantStore.list();
+        const grantId = request.intent.target?.grantId;
+        if (grantId) {
+            const exact = grants.filter((grant) => grant.grant_id === grantId);
+            if (!hasPermissionGrantSelectionContext(request))
+                return exact;
+            return exact.filter((grant) => permissionGrantMatchesRequest(grant, request));
+        }
+        const contextual = grants.filter((grant) => permissionGrantMatchesRequest(grant, request));
+        if (contextual.length > 0)
+            return contextual;
+        return hasPermissionGrantSelectionContext(request) ? [] : grants;
+    }
+    async selectSinglePermissionGrant(request) {
+        const grants = await this.matchPermissionGrants(request, { activeOnly: true });
+        if (grants.length === 0) {
+            return { ok: false, message: "No active PermissionGrant matches this chat/runtime context." };
+        }
+        if (grants.length > 1 && !request.intent.target?.grantId) {
+            return {
+                ok: false,
+                message: `Multiple active PermissionGrants match this context. Specify one grant id: ${grants.map((grant) => grant.grant_id).join(", ")}`,
+            };
+        }
+        return { ok: true, grant: grants[0] };
+    }
     async createInitialOperation(request) {
         const target = await this.resolveTarget(request);
         if (!target.ok) {
@@ -129,6 +628,7 @@ export class RuntimeControlService {
         }
         const requestedAt = this.nowIso();
         const risk = riskForIntent(request.intent);
+        const directTarget = directTargetFromIntent(request.intent);
         const operation = {
             operation_id: randomUUID(),
             kind: request.intent.kind,
@@ -147,7 +647,9 @@ export class RuntimeControlService {
                         ...(target.goalId ? { goal_id: target.goalId } : {}),
                     },
                 }
-                : {}),
+                : directTarget
+                    ? { target: directTarget }
+                    : {}),
             ...(risk ? { risk } : {}),
         };
         return this.operationStore.save(operation);
@@ -477,6 +979,8 @@ export class RuntimeControlService {
             message: operation.result?.message ?? ackMessage(operation.kind),
             operationId: operation.operation_id,
             state: operation.state,
+            ...(operation.result?.resume_outcome ? { resumeOutcome: operation.result.resume_outcome } : {}),
+            ...(operation.result?.companion_state_inspection ? { companionStateInspection: operation.result.companion_state_inspection } : {}),
         };
     }
     async update(operation, state, result) {
@@ -484,7 +988,14 @@ export class RuntimeControlService {
             ...operation,
             state,
             updated_at: this.nowIso(),
-            result,
+            result: {
+                ...operation.result,
+                ok: result.ok,
+                message: result.message,
+                ...(result.resumeOutcome ? { resume_outcome: result.resumeOutcome } : {}),
+                ...(result.companionStateInspection ? { companion_state_inspection: result.companionStateInspection } : {}),
+                ...(result.affectedRuntimeRefs ? { affected_runtime_refs: result.affectedRuntimeRefs } : {}),
+            },
         };
         return this.operationStore.save(updated);
     }
@@ -501,6 +1012,29 @@ export function isExecutableRuntimeControlKind(kind) {
         || kind === "resume_run"
         || kind === "cancel_run";
 }
+function isPermissionControlKind(kind) {
+    return kind === "inspect_permission_boundary"
+        || kind === "revoke_permission"
+        || kind === "narrow_permission"
+        || kind === "extend_permission"
+        || kind === "audit_permission_check";
+}
+function isCompanionWideControlKind(kind) {
+    return kind === "inspect_companion_state"
+        || kind === "enter_quiet_mode"
+        || kind === "leave_quiet_mode"
+        || kind === "pause_proactivity"
+        || kind === "resume_proactivity"
+        || kind === "suspend_companion"
+        || kind === "resume_companion"
+        || kind === "stop_all_quiet_work"
+        || kind === "stop_all_watches"
+        || kind === "suppress_nonessential_agenda"
+        || kind === "require_confirmation_for_proactivity";
+}
+function isSessionControlKind(kind) {
+    return kind === "inspect_session" || kind === "summarize_session_without_resuming";
+}
 function isRunControlKind(kind) {
     return kind === "inspect_run" || kind === "pause_run" || kind === "resume_run" || kind === "cancel_run" || kind === "finalize_run";
 }
@@ -512,7 +1046,8 @@ function requiresApproval(kind) {
         || kind === "pause_run"
         || kind === "resume_run"
         || kind === "cancel_run"
-        || kind === "finalize_run";
+        || kind === "finalize_run"
+        || kind === "extend_permission";
 }
 function normalizeReplyTarget(target) {
     return {
@@ -551,25 +1086,61 @@ function isPastIso(value) {
 function ackMessage(kind) {
     switch (kind) {
         case "restart_gateway":
-            return "gateway の再起動を開始します。復帰後にこの会話へ結果を返します。";
+            return "Gateway restart has started. A result will be returned to this conversation after recovery.";
         case "restart_daemon":
-            return "PulSeed daemon の再起動を開始します。復帰後にこの会話へ結果を返します。";
+            return "PulSeed daemon restart has started. A result will be returned to this conversation after recovery.";
         case "reload_config":
-            return "runtime 設定の再読み込みを開始します。";
+            return "Runtime configuration reload has started.";
         case "self_update":
-            return "PulSeed 自身の更新準備を開始します。実行前に内容を確認します。";
+            return "PulSeed self-update preparation has started. Changes will be reviewed before execution.";
         case "inspect_run":
-            return "runtime run の状況を確認しました。";
+            return "Runtime run status was inspected.";
         case "pause_run":
-            return "runtime run の safe pause を要求します。";
+            return "Runtime run safe pause was requested.";
         case "resume_run":
-            return "runtime run の再開を要求します。";
+            return "Runtime run resume was requested.";
         case "cancel_run":
-            return "runtime run のキャンセルを要求します。";
+            return "Runtime run cancellation was requested.";
         case "finalize_run":
-            return "runtime run の最終化 proposal を作成します。";
+            return "Runtime run finalization proposal will be created.";
+        case "inspect_permission_boundary":
+            return "Active permission boundary was inspected.";
+        case "revoke_permission":
+            return "Permission grant revocation was recorded.";
+        case "narrow_permission":
+            return "Permission grant narrowing was recorded.";
+        case "extend_permission":
+            return "Permission grant extension was recorded.";
+        case "audit_permission_check":
+            return "Permission grant audit was inspected.";
+        case "inspect_companion_state":
+            return "Companion state was inspected.";
+        case "enter_quiet_mode":
+            return "Quiet mode was enabled.";
+        case "leave_quiet_mode":
+            return "Quiet mode was disabled. Held items were not resumed automatically.";
+        case "pause_proactivity":
+            return "Proactivity pause was enabled.";
+        case "resume_proactivity":
+            return "Proactivity pause was disabled. Held items require re-evaluation.";
+        case "suspend_companion":
+            return "Companion suspend was enabled.";
+        case "resume_companion":
+            return "Companion suspend was disabled. Held items were not resumed automatically.";
+        case "stop_all_quiet_work":
+            return "Quiet-work stop request was recorded.";
+        case "stop_all_watches":
+            return "Watch stop request was recorded.";
+        case "suppress_nonessential_agenda":
+            return "Nonessential agenda suppression was recorded.";
+        case "require_confirmation_for_proactivity":
+            return "Confirmation was required for proactivity.";
+        case "inspect_session":
+            return "Runtime session was inspected.";
+        case "summarize_session_without_resuming":
+            return "Runtime session was summarized without resuming.";
         case "automation_control":
-            return "runtime automation control を記録しました。";
+            return "Runtime automation control was recorded.";
     }
 }
 function targetFromRunRequest(request) {
@@ -580,6 +1151,16 @@ function targetFromRunRequest(request) {
         ...(request.sessionId ? { sessionId: request.sessionId } : {}),
     };
 }
+function directTargetFromIntent(intent) {
+    const target = intent.target;
+    if (!target?.runId && !target?.sessionId && !target?.grantId)
+        return undefined;
+    return {
+        ...(target.runId ? { run_id: target.runId } : {}),
+        ...(target.sessionId ? { session_id: target.sessionId } : {}),
+        ...(target.grantId ? { grant_id: target.grantId } : {}),
+    };
+}
 function riskForIntent(intent) {
     if (intent.kind !== "finalize_run")
         return null;
@@ -592,4 +1173,320 @@ function riskForIntent(intent) {
 function blocked(message) {
     return { ok: false, result: { success: false, message, state: "blocked" } };
 }
+function applyCompanionControlState(runtimeItems, globalControls, activeControls) {
+    const inactiveHeldControlRefs = globalControls.filter((entry) => (entry.state === "inactive"
+        && controlRequiresReadmissionAfterLift(entry.control)
+        && entry.affected_runtime_refs.length > 0));
+    if (activeControls.length === 0 && inactiveHeldControlRefs.length === 0)
+        return runtimeItems;
+    const globalControlRefs = globalControls
+        .filter((entry) => entry.state === "active" || inactiveHeldControlRefs.includes(entry))
+        .map((entry) => entry.source_ref);
+    return runtimeItems.map((item) => {
+        const heldByControls = activeControls.filter((control) => controlHoldsRuntimeItem(control, item));
+        const historicallyHeldByControls = inactiveHeldControlRefs
+            .filter((entry) => entry.affected_runtime_refs.includes(item.item_id))
+            .map((entry) => entry.control);
+        const rejectedByControls = activeControls.filter((control) => controlRejectsRuntimeItem(control, item));
+        if (heldByControls.length === 0 && historicallyHeldByControls.length === 0 && rejectedByControls.length === 0) {
+            return item;
+        }
+        const controlled = {
+            ...item,
+            companion_control_state: {
+                active_controls: uniqueControls([
+                    ...item.companion_control_state.active_controls,
+                    ...activeControls,
+                ]),
+                global_control_refs: uniqueStrings([
+                    ...item.companion_control_state.global_control_refs,
+                    ...globalControlRefs,
+                ]),
+                held_by_controls: uniqueControls([
+                    ...item.companion_control_state.held_by_controls,
+                    ...heldByControls,
+                    ...historicallyHeldByControls,
+                ]),
+                rejected_by_controls: uniqueControls([
+                    ...item.companion_control_state.rejected_by_controls,
+                    ...rejectedByControls,
+                ]),
+                reason: "companion-wide global controls applied at runtime admission boundary",
+            },
+        };
+        return {
+            ...controlled,
+            control_policy: deriveRuntimeItemControlPolicy(controlled),
+        };
+    });
+}
+function companionControlEntry(input) {
+    return {
+        control: input.control,
+        state: input.state,
+        source_ref: `runtime-control:${input.operation.operation_id}`,
+        updated_at: input.operation.updated_at,
+        reason: input.operation.reason,
+        changed_by: input.operation.requested_by,
+        affected_runtime_refs: input.affectedRefs,
+        audit_refs: input.auditRefs ?? [`runtime-control-operation:${input.operation.operation_id}`],
+    };
+}
+function oneShotCompanionControls() {
+    return new Set([
+        "leave_quiet_mode",
+        "resume_proactivity",
+        "resume_companion",
+    ]);
+}
+function controlRequiresReadmissionAfterLift(control) {
+    return control === "enter_quiet_mode"
+        || control === "pause_proactivity"
+        || control === "suspend_companion"
+        || control === "stop_all_quiet_work"
+        || control === "stop_all_watches"
+        || control === "suppress_nonessential_agenda"
+        || control === "require_confirmation_for_proactivity";
+}
+function isDurableAgendaSuppressionControl(control) {
+    return control === "stop_all_quiet_work"
+        || control === "stop_all_watches"
+        || control === "suppress_nonessential_agenda";
+}
+function affectedRuntimeRefsForControl(control, runtimeItems) {
+    return runtimeItems
+        .filter((item) => activeRuntimeItem(item))
+        .filter((item) => {
+        if (control === "suspend_companion" || control === "resume_companion")
+            return true;
+        if (control === "stop_all_quiet_work")
+            return quietWorkRuntimeItem(item);
+        if (control === "stop_all_watches")
+            return item.type === "watch";
+        if (control === "suppress_nonessential_agenda")
+            return agendaRuntimeItem(item);
+        if (control === "enter_quiet_mode" || control === "pause_proactivity")
+            return agentOriginAdmissionItem(item);
+        if (control === "require_confirmation_for_proactivity")
+            return agentOriginAdmissionItem(item);
+        return false;
+    })
+        .map((item) => item.item_id);
+}
+function controlHoldsRuntimeItem(control, item) {
+    if (!activeRuntimeItem(item))
+        return false;
+    if (control === "suspend_companion")
+        return true;
+    if (control === "stop_all_quiet_work")
+        return quietWorkRuntimeItem(item);
+    if (control === "stop_all_watches")
+        return item.type === "watch";
+    if (control === "suppress_nonessential_agenda")
+        return agendaRuntimeItem(item);
+    return false;
+}
+function controlRejectsRuntimeItem(control, item) {
+    if (!activeRuntimeItem(item))
+        return false;
+    if (control === "suspend_companion")
+        return true;
+    if (control === "enter_quiet_mode" || control === "pause_proactivity")
+        return agentOriginAdmissionItem(item);
+    return false;
+}
+function activeRuntimeItem(item) {
+    return item.status === "running"
+        || item.status === "pending"
+        || item.status === "paused"
+        || item.status === "active"
+        || item.status === "mature";
+}
+function quietWorkRuntimeItem(item) {
+    if (item.source === "runtime-operation-store")
+        return false;
+    return item.type === "run" || item.type === "task" || item.type === "diff_proposal";
+}
+function quietWorkPauseTarget(item) {
+    const runId = backgroundRunIdFromRuntimeItem(item);
+    const sessionId = item.related_session_refs[0];
+    const goalId = item.related_goal_refs[0];
+    const target = {
+        ...(runId ? { run_id: runId } : {}),
+        ...(sessionId ? { session_id: sessionId } : {}),
+        ...(goalId ? { goal_id: goalId } : {}),
+    };
+    return Object.keys(target).length > 0 ? target : null;
+}
+function backgroundRunIdFromRuntimeItem(item) {
+    const prefix = "background-run:";
+    if (!item.item_id.startsWith(prefix))
+        return null;
+    return item.item_id.slice(prefix.length);
+}
+function quietWorkStopResult(itemRef, operation) {
+    return {
+        itemRef,
+        operationId: operation.operation_id,
+        state: operation.state,
+        ok: operation.result?.ok ?? false,
+    };
+}
+function agendaRuntimeItem(item) {
+    return item.type === "urge_candidate" || item.type === "agent_agenda_item";
+}
+function agentOriginAdmissionItem(item) {
+    return agendaRuntimeItem(item)
+        || item.type === "surface_projection"
+        || item.authority.speakable
+        || item.authority.can_create_urge
+        || item.authority.can_write_memory
+        || item.authority.can_update_surface
+        || item.authority.can_delegate_work;
+}
+function buildCompanionStateInspection(runtimeItems, snapshot) {
+    const inspectedItems = runtimeItems
+        .filter((item) => (item.authority.inspectable
+        && item.visibility_policy.inspectable
+        && item.control_policy.allowed_controls.includes("inspect_item")))
+        .filter((item) => companionInspectionItem(item, snapshot))
+        .map((item) => ({
+        ref: item.item_id,
+        type: item.type,
+        status: item.status,
+        posture: item.posture,
+        visibility_display: item.visibility_policy.display,
+        inspectable: item.visibility_policy.inspectable,
+        auditable: item.visibility_policy.auditable,
+        authority_scope: item.authority.approval_scope,
+        authority: {
+            resumable: item.authority.resumable,
+            actionable: item.authority.actionable,
+            speakable: item.authority.speakable,
+            can_create_urge: item.authority.can_create_urge,
+            can_update_surface: item.authority.can_update_surface,
+            can_write_memory: item.authority.can_write_memory,
+            can_delegate_work: item.authority.can_delegate_work,
+            requires_confirmation: item.authority.requires_confirmation,
+        },
+        staleness_outcomes: Object.fromEntries(Object.entries(item.staleness).map(([dimension, value]) => [dimension, value.outcome])),
+        allowed_controls: item.control_policy.allowed_controls,
+        repair_options: item.control_policy.repair_options,
+        audit_trace_refs: item.audit_trace_refs,
+    }));
+    const allRuntimeItemRefs = new Set(runtimeItems.map((item) => item.item_id));
+    const inspectableRuntimeItemRefs = new Set(inspectedItems.map((item) => item.ref));
+    const inspectableSnapshotRefs = (refs) => refs.filter((candidate) => (!allRuntimeItemRefs.has(candidate) || inspectableRuntimeItemRefs.has(candidate)));
+    return {
+        snapshot_id: snapshot.snapshot_id,
+        mode: snapshot.mode,
+        inspected_at: snapshot.computed_at,
+        active_controls: snapshot.control_overlays,
+        active_refs: inspectableSnapshotRefs(snapshot.active_refs),
+        held_runtime_refs: inspectableSnapshotRefs(snapshot.held_runtime_refs),
+        blocked_refs: inspectableSnapshotRefs(snapshot.blocked_refs),
+        hidden_refs: inspectedItems
+            .filter((item) => item.visibility_display !== "normal")
+            .map((item) => item.ref),
+        non_executable_refs: inspectedItems
+            .filter((item) => !runtimeItemGrantsExecution(item.authority))
+            .map((item) => item.ref),
+        repairable_refs: inspectedItems
+            .filter((item) => item.repair_options.length > 0)
+            .map((item) => item.ref),
+        runtime_items: inspectedItems,
+    };
+}
+function companionInspectionItem(item, snapshot) {
+    return item.visibility_policy.display !== "normal"
+        || snapshot.held_runtime_refs.includes(item.item_id)
+        || snapshot.blocked_refs.includes(item.item_id)
+        || !runtimeItemGrantsExecution(item.authority)
+        || item.control_policy.repair_options.length > 0
+        || Object.values(item.staleness).some((dimension) => dimension.outcome !== "current");
+}
+function runtimeItemGrantsExecution(authority) {
+    return authority.resumable
+        || authority.actionable
+        || authority.speakable
+        || authority.can_create_urge
+        || authority.can_update_surface
+        || authority.can_write_memory
+        || authority.can_delegate_work;
+}
+function formatCompanionStateSummary(snapshot, inspection) {
+    return [
+        `CompanionState ${snapshot.snapshot_id}: mode=${snapshot.mode}.`,
+        `active_controls=${snapshot.control_overlays.length > 0 ? snapshot.control_overlays.join(", ") : "none"}.`,
+        `active_refs=${snapshot.active_refs.length}.`,
+        `held_refs=${snapshot.held_runtime_refs.length}.`,
+        `blocked_refs=${snapshot.blocked_refs.length}.`,
+        inspection ? `hidden_items=${inspection.hidden_refs.length}.` : null,
+        inspection ? `non_executable_items=${inspection.non_executable_refs.length}.` : null,
+        inspection ? `repairable_items=${inspection.repairable_refs.length}.` : null,
+    ].filter((part) => Boolean(part)).join(" ");
+}
+function formatCompanionControlApplied(control, affectedRefs) {
+    const suffix = affectedRefs.length > 0
+        ? ` Affected runtime items: ${affectedRefs.join(", ")}.`
+        : " No currently active runtime items were affected.";
+    if (control === "leave_quiet_mode" || control === "resume_proactivity" || control === "resume_companion") {
+        return `${control} recorded. Held, stale, or suppressed runtime items were not resumed automatically.${suffix}`;
+    }
+    return `${control} recorded as companion-wide global control.${suffix}`;
+}
+function formatSessionInspection(session) {
+    return [
+        `Runtime session ${session.id}: ${session.status}.`,
+        `Kind: ${session.kind}.`,
+        session.title ? `Title: ${session.title}.` : null,
+        `Inspectable: true.`,
+        `Resumable: ${session.resumable ? "requires runtime admission" : "false"}.`,
+        `Updated: ${session.updated_at ?? "unknown"}.`,
+    ].filter((line) => Boolean(line)).join(" ");
+}
+function formatSessionSummaryOnly(session) {
+    return [
+        `Runtime session ${session.id} summary-only view: ${session.status}.`,
+        session.title ? `Title: ${session.title}.` : null,
+        `No action, speech, memory write, Surface refresh, or side-effect authority was granted.`,
+    ].filter((line) => Boolean(line)).join(" ");
+}
+function resumeBlockedByRuntimeItemPolicy(runId, item) {
+    if (item.companion_control_state.held_by_controls.includes("suspend_companion")
+        || item.companion_control_state.rejected_by_controls.includes("suspend_companion")) {
+        return {
+            outcome: "resume_rejected_safety",
+            message: `Runtime run ${runId} cannot resume while companion suspend state requires explicit re-admission.`,
+        };
+    }
+    if (item.companion_control_state.held_by_controls.length > 0 || item.companion_control_state.rejected_by_controls.length > 0) {
+        return {
+            outcome: "resume_requires_regrounding",
+            message: `Runtime run ${runId} is held by companion-wide controls and requires re-grounding before resume.`,
+        };
+    }
+    if (item.staleness.permission.outcome !== "current") {
+        return {
+            outcome: "resume_rejected_permission",
+            message: `Runtime run ${runId} cannot resume because permission state is ${item.staleness.permission.outcome}.`,
+        };
+    }
+    if (item.staleness.surface.outcome !== "current") {
+        return {
+            outcome: "resume_rejected_surface",
+            message: `Runtime run ${runId} cannot resume because Surface state is ${item.staleness.surface.outcome}.`,
+        };
+    }
+    return {
+        outcome: "resume_requires_regrounding",
+        message: `Runtime run ${runId} is not allowed by runtime item control policy: ${item.control_policy.reason}.`,
+    };
+}
+function uniqueControls(controls) {
+    return [...new Set(controls)];
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
 //# sourceMappingURL=runtime-control-service.js.map