@asc-agent/runtime 0.1.0

package/dist/core/operator/proceed.d.ts

@@ -0,0 +1,98 @@
+import type { Session } from '../model/entities.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+import type { CanonicalDrift, SessionRuntime } from '../runtime/session.ts';
+import { type EscalationLedger } from '../runtime/escalation.ts';
+import { type ExecutionVerdict } from '../runtime/execution-state.ts';
+/** proceed 진입 전 설정 검증 결과. 실 구현은 bootstrapGuard를 감싼다 — 새 판단 금지. */
+export type ConfigCheck = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+export type ProceedIntent = {
+    /** 사용자가 특정 세션을 지목했다. 자동 탐색과 semantics가 다르다 (C-03 §1.5). */
+    sessionId?: string;
+    /** 후보가 없을 때 초안에 실어 줄 목표 힌트. 확정이 아니다. */
+    goal?: string;
+};
+/** 후보 나열용 요약 — 사람이 고를 근거까지 함께 준다. */
+export type SessionCandidate = {
+    id: string;
+    status: Session['status'];
+    role: Session['role'];
+    goal: string;
+    /** 이 세션을 고르면 무슨 일이 일어나는지. */
+    wouldDo: 'start' | 'resume' | 'continue';
+};
+/** 실행 가능 outcome이 Host에 넘겨주는 것 — 계약과 이어받을 지점. */
+type Handout = {
+    contract: Session;
+    doneCriteria: string[];
+    checkpoint?: Session['checkpoint'];
+    /** 지금 무엇이 막혔고 무엇이 가는가 (C-13 §6). 상신 원장이 없으면 없다. */
+    gate?: ExecutionVerdict;
+    /** 열려 있는 상신 id. 진행 화면이 "판단 필요 없음"이라고 말하지 않게 하는 근거다. */
+    awaiting?: string[];
+};
+export type ProceedOutcome = ({
+    kind: 'STARTED';
+} & Handout) | ({
+    kind: 'RESUMED';
+} & Handout) | ({
+    kind: 'CONTINUE_ACTIVE';
+} & Handout) | {
+    kind: 'NEEDS_SELECTION';
+    candidates: SessionCandidate[];
+} | {
+    kind: 'PROPOSE_CONTRACT';
+    /** 초안일 뿐이다 — issue는 Controller 승인 후 별도 행위 (C-03 §1.3). */
+    draft: {
+        role: Session['role'];
+        goal: string;
+        doneCriteria: string[];
+    };
+}
+/**
+ * 미해소 상신이 실행 가능한 node를 전부 덮었다 (C-13 §6).
+ *
+ * BLOCKED와 다르다: 세션은 PAUSED 그대로이고, 경계가 풀리면 그대로 이어진다.
+ * **전이를 일으키지 않는다** — 사람이 결정할 때까지 기다리는 것이지 실패가 아니다.
+ */
+ | {
+    kind: 'HELD';
+    detail: string;
+    verdict: ExecutionVerdict;
+    escalations: string[];
+} | {
+    kind: 'BLOCKED_CONFIG';
+    detail: string;
+} | {
+    kind: 'BLOCKED_CANONICAL';
+    detail: string;
+    drifts?: CanonicalDrift[];
+} | {
+    kind: 'FAILED';
+    reason: 'NOT_FOUND' | 'SESSION_BLOCKED' | 'NOT_RUNNABLE' | 'TRANSITION';
+    detail: string;
+};
+export type OperatorDeps = {
+    store: StateStore;
+    sessions: SessionRuntime;
+    /**
+     * 상신 원장 (C-13). 주면 proceed가 **막힌 node만** 보고 판단한다 —
+     * 주지 않으면 예전처럼 상태만 보고 간다(기존 호출자 무손상).
+     */
+    escalations?: EscalationLedger;
+    /**
+     * 필수다. 모든 진입이 bootstrap/profile.lock 검증을 지난다 — Surface가 어디든.
+     * 실 조립은 factory(cli의 createOperator)가 bootstrapGuard로 고정한다.
+     */
+    guard: () => Promise<ConfigCheck>;
+};
+export declare class Operator {
+    #private;
+    constructor(deps: OperatorDeps);
+    proceed(intent?: ProceedIntent): Promise<ProceedOutcome>;
+}
+export {};

package/dist/core/operator/proceed.js

@@ -0,0 +1,167 @@
+// Generic Operator — "ASC로 진행해"의 provider-neutral 구현 (C-03 §1).
+//
+// 사람이 CLI 명령을 조립하던 절차를 하나의 진입으로 수렴한다. 판단은 전부 기존 것을
+// 쓴다: 상태 전이는 SessionRuntime, 설정 검증은 bootstrap guard, 정본 판정은
+// checkCanonical. 이 파일에 새 판단 로직이 생기면 그건 Core를 우회하는 두 번째 길이다.
+//
+// guard는 optional이 아니다. CLI가 아닌 Host Adapter가 직접 불러도 profile.lock 검증을
+// 건너뛸 수 없어야 하며(C-03 §1.2), 정본 조립은 Surface가 아니라 factory가 진다.
+import { proceedGateFacts } from "../runtime/escalation.js";
+import { deriveExecutionState } from "../runtime/execution-state.js";
+const RUNNABLE = new Set(['READY', 'PAUSED', 'ACTIVE']);
+export class Operator {
+    #store;
+    #sessions;
+    #escalations;
+    #guard;
+    constructor(deps) {
+        this.#store = deps.store;
+        this.#sessions = deps.sessions;
+        this.#escalations = deps.escalations;
+        this.#guard = deps.guard;
+    }
+    async proceed(intent = {}) {
+        const config = await this.#guard();
+        if (!config.ok)
+            return { kind: 'BLOCKED_CONFIG', detail: config.detail };
+        // 명시 지정 — 사용자가 가리킨 그 세션만 본다. 다른 것을 권하지 않는다 (C-03 §1.5).
+        if (intent.sessionId) {
+            const session = await this.#store.get('session', intent.sessionId);
+            if (!session) {
+                return { kind: 'FAILED', reason: 'NOT_FOUND', detail: `세션 '${intent.sessionId}' 을 찾지 못했다` };
+            }
+            return this.#advance(session);
+        }
+        // 자동 탐색 — 실행 가능한 것만 후보다. archive는 collect가 이미 치웠다.
+        const candidates = (await this.#store.list('session')).filter((s) => RUNNABLE.has(s.status));
+        if (candidates.length === 0) {
+            // 자동 issue 금지. 초안을 제안할 수는 있으나 발급은 Controller 승인 후 별도 행위다.
+            return {
+                kind: 'PROPOSE_CONTRACT',
+                draft: { role: 'implementer', goal: intent.goal ?? '', doneCriteria: [] },
+            };
+        }
+        if (candidates.length > 1) {
+            // 임의 선택 금지 — 잘못 고른 세션 위에서 작업이 시작되는 것보다 한 번 묻는 게 싸다.
+            return {
+                kind: 'NEEDS_SELECTION',
+                candidates: candidates.map((s) => ({
+                    id: s.id,
+                    status: s.status,
+                    role: s.role,
+                    goal: s.goal,
+                    wouldDo: s.status === 'READY' ? 'start' : s.status === 'PAUSED' ? 'resume' : 'continue',
+                })),
+            };
+        }
+        return this.#advance(candidates[0]);
+    }
+    /** 상태별로 한 걸음. 전이는 전부 SessionRuntime을 지난다 — 우회 경로 없음. */
+    async #advance(session) {
+        switch (session.status) {
+            case 'READY':
+                return this.#mapStart(await this.#sessions.start(session.id), 'STARTED', session.id);
+            case 'PAUSED': {
+                // **checkpoint를 발행했다는 이유로 멈추지 않는다** (C-13 불변식 ④).
+                // 멈추는 근거는 미해소 상신뿐이고, 그것도 막힌 node에 한한다.
+                const gate = await this.#gate(session);
+                if (gate && gate.runnable.length === 0 && gate.escalations.length > 0) {
+                    return {
+                        kind: 'HELD',
+                        detail: `실행 가능한 항목이 없다 — 상신 ${gate.escalations.length}건이 전부를 덮었다`,
+                        verdict: gate.verdict,
+                        escalations: gate.escalations,
+                    };
+                }
+                const resumed = await this.#mapStart(await this.#sessions.resume(session.id), 'RESUMED', session.id);
+                return gate && 'contract' in resumed
+                    ? { ...resumed, gate: gate.verdict, ...(gate.escalations.length > 0 ? { awaiting: gate.escalations } : {}) }
+                    : resumed;
+            }
+            case 'ACTIVE': {
+                // 이미 검증됐다고 가정하지 않는다 — 이어가기 전에도 정본을 다시 본다 (C-03 §1.6).
+                const canonical = await this.#sessions.checkCanonical(session.id);
+                if (canonical.status === 'DRIFT') {
+                    return { kind: 'BLOCKED_CANONICAL', detail: '정본이 발급 시점과 다르다', drifts: canonical.drifts };
+                }
+                if (canonical.status === 'UNAVAILABLE') {
+                    return { kind: 'BLOCKED_CANONICAL', detail: canonical.detail };
+                }
+                if (canonical.status === 'NOT_FOUND') {
+                    return { kind: 'FAILED', reason: 'NOT_FOUND', detail: `세션 '${session.id}' 을 찾지 못했다` };
+                }
+                // 돌고 있는 세션도 같은 판정을 받는다. PAUSED에만 걸면 "한 번 재개된 뒤에는
+                // 전부 막혀도 계속 간다고 말하는" 구멍이 생긴다 (실제로 그랬다).
+                const gate = await this.#gate(session);
+                if (gate && gate.runnable.length === 0 && gate.escalations.length > 0) {
+                    return {
+                        kind: 'HELD',
+                        detail: `실행 가능한 항목이 없다 — 상신 ${gate.escalations.length}건이 전부를 덮었다`,
+                        verdict: gate.verdict,
+                        escalations: gate.escalations,
+                    };
+                }
+                return {
+                    kind: 'CONTINUE_ACTIVE',
+                    ...handout(session),
+                    ...(gate ? { gate: gate.verdict } : {}),
+                    ...(gate && gate.escalations.length > 0 ? { awaiting: gate.escalations } : {}),
+                };
+            }
+            case 'BLOCKED':
+                return {
+                    kind: 'FAILED',
+                    reason: 'SESSION_BLOCKED',
+                    detail: `${session.id} 는 BLOCKED — Controller가 해소해야 진행할 수 있다`,
+                };
+            case 'DONE':
+            case 'FAILED':
+                return {
+                    kind: 'FAILED',
+                    reason: 'NOT_RUNNABLE',
+                    detail: `${session.id} 는 ${session.status} — 이어갈 수 없는 상태다`,
+                };
+        }
+    }
+    /**
+     * 이 세션이 지금 어디까지 갈 수 있는가. 원장이 없으면 판단하지 않는다 —
+     * 없는 근거로 세우지 않는다.
+     */
+    async #gate(session) {
+        if (!this.#escalations)
+            return null;
+        const pending = (await this.#escalations.pending()).filter((record) => record.sessionId === session.id);
+        const facts = proceedGateFacts(pending, session.doneCriteria);
+        return {
+            verdict: deriveExecutionState({
+                doneCriteria: session.doneCriteria,
+                ...(facts.waitingOn.length > 0 ? { waitingOn: facts.waitingOn } : {}),
+                ...(facts.conditions.length > 0 ? { conditions: facts.conditions } : {}),
+            }),
+            runnable: facts.runnable,
+            escalations: pending.map((record) => record.escalationId),
+        };
+    }
+    async #mapStart(outcome, kind, id) {
+        if (outcome.ok)
+            return { kind, ...handout(outcome.entity) };
+        if (outcome.reason === 'CANONICAL_DRIFT') {
+            return { kind: 'BLOCKED_CANONICAL', detail: '정본이 발급 시점과 다르다', drifts: outcome.drifts };
+        }
+        if (outcome.reason === 'CANONICAL_UNAVAILABLE') {
+            return { kind: 'BLOCKED_CANONICAL', detail: outcome.detail };
+        }
+        if (outcome.reason === 'NOT_FOUND') {
+            return { kind: 'FAILED', reason: 'NOT_FOUND', detail: `세션 '${id}' 을 찾지 못했다` };
+        }
+        const detail = outcome.reason === 'REJECTED' ? outcome.failure.message : `전이 실패: ${outcome.reason}`;
+        return { kind: 'FAILED', reason: 'TRANSITION', detail };
+    }
+}
+function handout(session) {
+    return {
+        contract: session,
+        doneCriteria: session.doneCriteria,
+        ...(session.checkpoint ? { checkpoint: session.checkpoint } : {}),
+    };
+}

package/dist/core/operator/progress.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+import type { RuntimeBindings } from './runtime-binding.ts';
+/**
+ * 사용자 판단이 지금 필요한가. 단순 BLOCKED 여부보다 이게 사람에게 더 중요하다 —
+ * "내가 지금 뭘 해야 하지"에 바로 답한다.
+ */
+export declare const DecisionNeed: z.ZodEnum<["NONE", "LATER", "NOW"]>;
+export type DecisionNeed = z.infer<typeof DecisionNeed>;
+/** 독립 검증의 관측 상태. 자기 보고(Handoff.verified)와 다른 축이다. */
+export declare const VerifierState: z.ZodEnum<["NONE", "RUNNING", "PASS", "FAIL"]>;
+export type VerifierState = z.infer<typeof VerifierState>;
+export declare const ProgressReport: z.ZodObject<{
+    logicalSessionId: z.ZodString;
+    /** 지금 무엇을 하는 중인가 — 한 줄. */
+    phase: z.ZodString;
+    /** 무엇이 끝났는가. 파일 하나·테스트 하나가 아니라 의미 있는 묶음만. */
+    milestones: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 다음에는 무엇을 하는가. */
+    nextStep: z.ZodOptional<z.ZodString>;
+    /** 확인이 필요한 항목 — 작업을 막지는 않는 것들. */
+    unresolved: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    needsUserDecision: z.ZodDefault<z.ZodEnum<["NONE", "LATER", "NOW"]>>;
+    /**
+     * NOW일 때 사람이 어디서 결정하는지. 판단 요청의 정본은 계속 ApprovalRequest/Inbox다 —
+     * Progress가 두 번째 결정 창구가 되면 control plane이 갈라진다.
+     */
+    decisionRef: z.ZodOptional<z.ZodString>;
+    verifier: z.ZodDefault<z.ZodEnum<["NONE", "RUNNING", "PASS", "FAIL"]>>;
+    verifierDetail: z.ZodOptional<z.ZodString>;
+    /**
+     * 종결 후 보존되는 최종 보고. DONE 즉시 삭제하면 "무엇을 마쳤나"를 볼 수단이 사라진다 —
+     * live projection 정리는 collect가 하고, terminal view는 남긴다.
+     */
+    terminal: z.ZodDefault<z.ZodBoolean>;
+    /** 기록한 Physical Session. 승계 후 옛 Host가 덮어쓰는 것을 막는 근거다. */
+    recordedBy: z.ZodString;
+    lastUpdatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    verifier: "NONE" | "RUNNING" | "PASS" | "FAIL";
+    unresolved: string[];
+    logicalSessionId: string;
+    phase: string;
+    milestones: string[];
+    needsUserDecision: "NONE" | "LATER" | "NOW";
+    terminal: boolean;
+    recordedBy: string;
+    lastUpdatedAt: string;
+    nextStep?: string | undefined;
+    decisionRef?: string | undefined;
+    verifierDetail?: string | undefined;
+}, {
+    logicalSessionId: string;
+    phase: string;
+    recordedBy: string;
+    lastUpdatedAt: string;
+    verifier?: "NONE" | "RUNNING" | "PASS" | "FAIL" | undefined;
+    unresolved?: string[] | undefined;
+    milestones?: string[] | undefined;
+    nextStep?: string | undefined;
+    needsUserDecision?: "NONE" | "LATER" | "NOW" | undefined;
+    decisionRef?: string | undefined;
+    verifierDetail?: string | undefined;
+    terminal?: boolean | undefined;
+}>;
+export type ProgressReport = z.infer<typeof ProgressReport>;
+/** 기록 입력 — 저장 책임 필드(recordedBy·lastUpdatedAt)는 서비스가 채운다. */
+export type ProgressInput = {
+    phase: string;
+    milestones?: string[];
+    nextStep?: string;
+    unresolved?: string[];
+    needsUserDecision?: DecisionNeed;
+    decisionRef?: string;
+    verifier?: VerifierState;
+    verifierDetail?: string;
+    terminal?: boolean;
+};
+export type ReportOutcome = {
+    ok: true;
+    report: ProgressReport;
+} | {
+    ok: false;
+    reason: 'NOT_OWNER';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'INVALID';
+    detail: string;
+};
+export type ProgressDeps = {
+    /** Adapter가 넘기는 격리 저장소. Core entity를 건드리지 않는 유일한 이유다. */
+    scope: ScopedStore;
+    /**
+     * 기록 권한 판정용. owner인 Physical Session만 쓴다 — RuntimeBinding이 이미
+     * 단일 소유권을 정해 뒀으므로 여기서 두 번째 권한 모델을 만들지 않는다.
+     */
+    bindings: RuntimeBindings;
+    now?: () => string;
+    /** History 기록. 없으면 남기지 않는다(테스트·비-store 환경). */
+    appendHistory?: (entry: {
+        at: string;
+        actor: string;
+        kind: string;
+        ref: string;
+        detail?: string;
+    }) => Promise<void>;
+};
+export declare class ProgressService {
+    #private;
+    constructor(deps: ProgressDeps);
+    /**
+     * 진행 보고를 기록한다. Session entity는 읽지도 쓰지도 않는다 —
+     * canonical state와 무관함이 호출 경로에서부터 보장돼야 한다.
+     */
+    report(logicalSessionId: string, physicalSessionId: string, input: ProgressInput): Promise<ReportOutcome>;
+    get(logicalSessionId: string): Promise<ProgressReport | null>;
+    /**
+     * collect 시점의 live projection 정리. terminal 보고는 남긴다 — 완료 화면이
+     * 사라지면 "무엇을 마쳤나"를 볼 수단이 없어진다.
+     * @returns 실제로 지운 세션 id
+     */
+    collect(closedSessionIds: readonly string[]): Promise<string[]>;
+}

package/dist/core/operator/progress.js

@@ -0,0 +1,135 @@
+// Semantic Progress — 작업 "중" 가시성의 정본 (B-17, post-b16-candidates P1).
+//
+// 왜 별도 구조인가: 사람이 알고 싶은 것은 "내 작업이 지금 어떻게 되고 있는가"인데,
+// canonical Session state는 READY/ACTIVE/PAUSED/DONE 넷뿐이라 23분 동안 ACTIVE 하나로
+// 침묵한다(B-16 friction ④ — 사용자가 중간보고를 직접 요청했다).
+//
+// 불변조건 (이 파일의 존재 이유):
+//   Runtime Progress ≠ Canonical Session State.
+//   Agent가 "80% 완료"라고 보고해도 Session.status는 변하지 않는다. 그래서 이 모듈은
+//   SessionRuntime을 import하지 않는다 — 전이 경로가 아예 없어야 실수로도 못 바꾼다.
+//   저장도 EntityMap 밖(ScopedStore)이라 Session 파일에 손이 닿지 않는다.
+//
+// Checkpoint와의 관계: Checkpoint는 Physical Run 승계 정보(PAUSED의 필수 요건)이고
+// Progress는 표시용 projection이다. 병합하지 않으며, Checkpoint lifecycle도 건드리지
+// 않는다 — ACTIVE 세션에 남아 있는 옛 checkpoint를 현재 진행으로 읽지 않는 것은
+// Renderer의 규칙이다 (render.ts).
+import { z } from 'zod';
+/**
+ * 사용자 판단이 지금 필요한가. 단순 BLOCKED 여부보다 이게 사람에게 더 중요하다 —
+ * "내가 지금 뭘 해야 하지"에 바로 답한다.
+ */
+export const DecisionNeed = z.enum([
+    'NONE', // 계속 진행 가능
+    'LATER', // 미확정 항목 있음 — 완료 시 함께 판단
+    'NOW', // 여기서 멈췄다 — 판단 없이 다음 단계 불가
+]);
+/** 독립 검증의 관측 상태. 자기 보고(Handoff.verified)와 다른 축이다. */
+export const VerifierState = z.enum(['NONE', 'RUNNING', 'PASS', 'FAIL']);
+export const ProgressReport = z.object({
+    logicalSessionId: z.string().min(1),
+    /** 지금 무엇을 하는 중인가 — 한 줄. */
+    phase: z.string().min(1),
+    /** 무엇이 끝났는가. 파일 하나·테스트 하나가 아니라 의미 있는 묶음만. */
+    milestones: z.array(z.string()).default([]),
+    /** 다음에는 무엇을 하는가. */
+    nextStep: z.string().optional(),
+    /** 확인이 필요한 항목 — 작업을 막지는 않는 것들. */
+    unresolved: z.array(z.string()).default([]),
+    needsUserDecision: DecisionNeed.default('NONE'),
+    /**
+     * NOW일 때 사람이 어디서 결정하는지. 판단 요청의 정본은 계속 ApprovalRequest/Inbox다 —
+     * Progress가 두 번째 결정 창구가 되면 control plane이 갈라진다.
+     */
+    decisionRef: z.string().optional(),
+    verifier: VerifierState.default('NONE'),
+    verifierDetail: z.string().optional(),
+    /**
+     * 종결 후 보존되는 최종 보고. DONE 즉시 삭제하면 "무엇을 마쳤나"를 볼 수단이 사라진다 —
+     * live projection 정리는 collect가 하고, terminal view는 남긴다.
+     */
+    terminal: z.boolean().default(false),
+    /** 기록한 Physical Session. 승계 후 옛 Host가 덮어쓰는 것을 막는 근거다. */
+    recordedBy: z.string().min(1),
+    lastUpdatedAt: z.string().min(1),
+});
+const keyOf = (logicalSessionId) => `progress:${logicalSessionId}`;
+export class ProgressService {
+    #scope;
+    #bindings;
+    #now;
+    #appendHistory;
+    constructor(deps) {
+        this.#scope = deps.scope;
+        this.#bindings = deps.bindings;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+        if (deps.appendHistory)
+            this.#appendHistory = deps.appendHistory;
+    }
+    /**
+     * 진행 보고를 기록한다. Session entity는 읽지도 쓰지도 않는다 —
+     * canonical state와 무관함이 호출 경로에서부터 보장돼야 한다.
+     */
+    async report(logicalSessionId, physicalSessionId, input) {
+        const binding = await this.#bindings.get(logicalSessionId);
+        if (!binding) {
+            return {
+                ok: false,
+                reason: 'NOT_OWNER',
+                detail: `${logicalSessionId} 에 Runtime이 붙어 있지 않다 — 먼저 소유권을 주장하라`,
+            };
+        }
+        if (binding.physicalSessionId !== physicalSessionId) {
+            // 승계 후 죽지 않은 옛 Host가 계속 쓰면 표시가 오염된다. owner만 쓴다.
+            return {
+                ok: false,
+                reason: 'NOT_OWNER',
+                detail: `${logicalSessionId} 의 owner가 아니다 (현재 owner: ${binding.physicalSessionId})`,
+            };
+        }
+        const at = this.#now();
+        const parsed = ProgressReport.safeParse({
+            logicalSessionId,
+            ...input,
+            recordedBy: physicalSessionId,
+            lastUpdatedAt: at,
+        });
+        if (!parsed.success) {
+            return { ok: false, reason: 'INVALID', detail: parsed.error.issues.map((i) => i.message).join('; ') };
+        }
+        // 갱신은 last-write-wins다. 표시 전용이고 owner가 하나뿐이라 수용한다 —
+        // 원자성이 필요한 것(소유권·전이)은 각자 다른 곳에서 이미 지키고 있다.
+        await this.#scope.set(keyOf(logicalSessionId), JSON.stringify(parsed.data));
+        await this.#appendHistory?.({
+            at,
+            actor: physicalSessionId,
+            kind: 'session_progress',
+            ref: logicalSessionId,
+            detail: parsed.data.phase,
+        });
+        return { ok: true, report: parsed.data };
+    }
+    async get(logicalSessionId) {
+        const raw = await this.#scope.get(keyOf(logicalSessionId));
+        if (!raw)
+            return null;
+        const parsed = ProgressReport.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    /**
+     * collect 시점의 live projection 정리. terminal 보고는 남긴다 — 완료 화면이
+     * 사라지면 "무엇을 마쳤나"를 볼 수단이 없어진다.
+     * @returns 실제로 지운 세션 id
+     */
+    async collect(closedSessionIds) {
+        const removed = [];
+        for (const id of closedSessionIds) {
+            const current = await this.get(id);
+            if (!current || current.terminal)
+                continue;
+            await this.#scope.delete(keyOf(id));
+            removed.push(id);
+        }
+        return removed;
+    }
+}

package/dist/core/operator/render.d.ts

@@ -0,0 +1,34 @@
+import type { Session } from '../model/entities.ts';
+import type { ProgressReport } from './progress.ts';
+export type RenderInput = {
+    /**
+     * 종결·archive 후에는 세션 entity가 활성 목록에 없다. 그때도 "무엇을 마쳤나"는
+     * 보여야 하므로 없어도 렌더한다 — 최종 화면이 사라지면 완료를 확인할 수단이 없다.
+     */
+    session: Session | null;
+    progress: ProgressReport | null;
+    /**
+     * 관찰된 활동 신호. **진척이 아니다** — 도구가 한 번 돌았다는 사실까지다.
+     * 없거나 오래됐다고 "멈췄다"고 말하지 않는다: 파일만 고치는 구간, 생각하는 구간,
+     * 하위 작업을 기다리는 구간에는 애초에 신호가 없다 (B-18).
+     */
+    liveness?: {
+        lastActivityAt: string;
+        lastTool?: string;
+    };
+    /**
+     * 지금 사람의 결정을 기다리는 것들 (상신·요청 참조).
+     *
+     * `progress.needsUserDecision` 은 **일하는 쪽의 신고**다. 신고가 없거나 NONE이어도
+     * 열린 상신이 있으면 판단은 실제로 필요하다 — 그때 "판단 필요 없음"이라고 말하는
+     * 화면은 거짓말이다 (B-65 dogfood에서 잡힌 것). 여기 값이 있으면 그것이 이긴다.
+     */
+    awaiting?: readonly string[];
+    now?: Date;
+};
+/** 사람에게 보여줄 본문과, 그 아래 붙는 작은 상세 한 줄. */
+export type RenderedProgress = {
+    body: string[];
+    detail: string;
+};
+export declare function renderProgress(input: RenderInput): RenderedProgress;