sortie-dogs 0.6.0 → 0.7.0

package/README.md

@@ -1,9 +1,13 @@
 # Sortie-dogs
 
-**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
-
-> **Project status: Experimental / unsupported.** No stability, compatibility,
-> or support guarantees are provided. Mk2A2 remains the canonical internal workflow.
+**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
+
+Sortie-dogs is an execution harness for OpenCode, applying harness-engineering
+principles through mechanical write boundaries, validation, review, and bounded
+orchestration.
+
+> **Project status: Beta.** Stable in regular use. As a pre-1.0 release,
+> configuration and runtime assets may still change between releases.
 
 [![npm](https://img.shields.io/npm/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
 [![license](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
@@ -20,7 +24,7 @@ Requirements: Node.js 22.6 or newer, npm, and OpenCode.
 
 Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [CLI testing](docs/cli-testing.md)
 
-Release: [v0.6.0](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.6.0)
+Release: [v0.7.0](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.7.0)
 
 ## Quick start
 
@@ -151,7 +155,8 @@ Optional settings in `.opencode/sortie-dogs.json`:
   "continuation": { "enabled": true, "maxAutoContinues": 10 },
   "reflection": {
     "enabled": false,
-    "layers": { "run": true, "project": true, "global": false }
+    "layers": { "run": true, "project": true, "global": false },
+    "maxInjectedTokens": 500
   }
 }
 ```
@@ -201,6 +206,10 @@ global file for durable global settings.
   to enabled after opt-in; the cross-project global storage layer remains
   disabled unless explicitly enabled. Child and non-coordinator sessions fail
   closed, and `SORTIE_REFLECTION=0` is an immediate kill switch. The coordinator
+  injects the governing `REFLECTION_POLICY` only while reflection is enabled.
+  `maxInjectedTokens` budgets the dynamic `SORTIE_PROCESS_REFLECTIONS` heading
+  and persisted entry lines; the policy is outside that entry budget.
+  The coordinator
   evaluates it only after a resolved blocker/review defect and at a terminal
   unit, with a maximum of three records per run; routine bugs and external
   failures are never journaled.

package/dist/asset-version.d.ts

@@ -2,5 +2,5 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export declare const RUNTIME_ASSET_VERSION = "0.3.49-run-metrics-v1";
+export declare const RUNTIME_ASSET_VERSION = "0.3.51-state-observability-v1";
 export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION;

package/dist/asset-version.js

@@ -2,4 +2,4 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export const RUNTIME_ASSET_VERSION = "0.3.49-run-metrics-v1";
+export const RUNTIME_ASSET_VERSION = "0.3.51-state-observability-v1";

package/dist/core/retained-state.d.ts

@@ -0,0 +1,54 @@
+export declare const RETAINED_STATE_EXTENSION: "sortie-dogs/retained-state";
+export declare const RETAINED_STATE_SCHEMA_VERSION: "0.1";
+export declare const RETAINED_STATE_AUTHORITY: "shadow";
+export declare const MAX_RETAINED_STATE_BYTES: number;
+export declare const MAX_RETAINED_STATE_ITEMS = 12;
+export declare const MAX_RETAINED_STATE_WARNINGS = 8;
+export interface RetainedValidationAttempt {
+    readonly command: string;
+    readonly exit: number | null;
+    readonly fingerprint: string;
+}
+export interface NextEvidenceDecision {
+    readonly schema_version: "0.1";
+    readonly authority: "shadow";
+    readonly gap_id: string;
+    readonly blocked_acceptance: string;
+    readonly question: string;
+    readonly expected_discrimination: string;
+    readonly action: string;
+    readonly stop_condition: string;
+}
+export interface AdmissionReceipt {
+    readonly evidence_id: string;
+    readonly source_agent: string;
+    readonly source_revision: string;
+    readonly evidence_fingerprint: string;
+    readonly supports: readonly string[];
+    readonly contradicts: readonly string[];
+    readonly freshness_basis: string;
+    readonly status: "recorded" | "recorded_with_warnings";
+    readonly warnings: readonly string[];
+}
+export interface RetainedStateCapsule {
+    readonly schema_version: "0.1";
+    readonly authority: "shadow";
+    readonly task_id: string;
+    readonly acceptance_fingerprint: string;
+    readonly source_manifest: "none" | readonly string[];
+    readonly operation_manifest: "none" | string;
+    readonly validation_history: readonly RetainedValidationAttempt[];
+    readonly blockers: readonly string[];
+    readonly next_action: string;
+    readonly next_evidence_decision?: NextEvidenceDecision;
+    readonly admissions?: readonly AdmissionReceipt[];
+}
+export interface RetainedStateWarning {
+    readonly code: "malformed" | "oversize" | "optional_invalid";
+    readonly message: string;
+}
+export interface RetainedStateInspection {
+    readonly capsule: RetainedStateCapsule | undefined;
+    readonly warnings: readonly RetainedStateWarning[];
+}
+export declare function inspectRetainedStateCapsule(handoff: unknown): RetainedStateInspection;

package/dist/core/retained-state.js

@@ -0,0 +1,81 @@
+export const RETAINED_STATE_EXTENSION = "sortie-dogs/retained-state";
+export const RETAINED_STATE_SCHEMA_VERSION = "0.1";
+export const RETAINED_STATE_AUTHORITY = "shadow";
+export const MAX_RETAINED_STATE_BYTES = 16 * 1024;
+export const MAX_RETAINED_STATE_ITEMS = 12;
+export const MAX_RETAINED_STATE_WARNINGS = 8;
+const MAX_SHORT = 256;
+const MAX_TEXT = 1000;
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isText = (value, max = MAX_TEXT) => typeof value === "string" && value.length > 0 && value.length <= max;
+const isBoundedList = (value, max = MAX_RETAINED_STATE_ITEMS) => Array.isArray(value) && value.length <= max;
+const isSourceManifest = (value) => value === "none" || (isBoundedList(value) && value.length === new Set(value).size && value.every((item) => isText(item, 512)));
+function validAttempt(value) {
+    const exit = isObject(value) ? value.exit : undefined;
+    return isObject(value) && isText(value.command, 1000) && (exit === null || (typeof exit === "number" && Number.isInteger(exit) && exit >= -1 && exit <= 255)) && isText(value.fingerprint, MAX_SHORT);
+}
+function validDecision(value) {
+    return isObject(value) && value.schema_version === "0.1" && value.authority === "shadow" &&
+        isText(value.gap_id, MAX_SHORT) && isText(value.blocked_acceptance) && isText(value.question) &&
+        isText(value.expected_discrimination) && isText(value.action) && isText(value.stop_condition);
+}
+function validAdmission(value) {
+    return isObject(value) && isText(value.evidence_id, MAX_SHORT) && isText(value.source_agent, MAX_SHORT) &&
+        isText(value.source_revision, MAX_SHORT) && isText(value.evidence_fingerprint, MAX_SHORT) &&
+        isBoundedList(value.supports) && value.supports.every((item) => isText(item, MAX_SHORT)) &&
+        isBoundedList(value.contradicts) && value.contradicts.every((item) => isText(item, MAX_SHORT)) &&
+        isText(value.freshness_basis) && (value.status === "recorded" || value.status === "recorded_with_warnings") &&
+        isBoundedList(value.warnings, MAX_RETAINED_STATE_WARNINGS) && value.warnings.every((item) => isText(item, MAX_SHORT));
+}
+export function inspectRetainedStateCapsule(handoff) {
+    if (!isObject(handoff) || !isObject(handoff.ext) || !(RETAINED_STATE_EXTENSION in handoff.ext)) {
+        return { capsule: undefined, warnings: [] };
+    }
+    const raw = handoff.ext[RETAINED_STATE_EXTENSION];
+    let bytes;
+    try {
+        bytes = new TextEncoder().encode(JSON.stringify(raw)).byteLength;
+    }
+    catch {
+        return { capsule: undefined, warnings: [{ code: "malformed", message: "Retained state was ignored because it is malformed." }] };
+    }
+    if (bytes > MAX_RETAINED_STATE_BYTES)
+        return { capsule: undefined, warnings: [{ code: "oversize", message: "Retained state was ignored because it exceeds its bound." }] };
+    if (!isObject(raw) || raw.schema_version !== "0.1" || raw.authority !== "shadow" || !isText(raw.task_id, MAX_SHORT) ||
+        !isText(raw.acceptance_fingerprint, MAX_SHORT) || !isSourceManifest(raw.source_manifest) ||
+        !(raw.operation_manifest === "none" || isText(raw.operation_manifest, 512)) ||
+        !isBoundedList(raw.validation_history) || !raw.validation_history.every(validAttempt) ||
+        !isBoundedList(raw.blockers) || !raw.blockers.every((item) => isText(item)) || !isText(raw.next_action)) {
+        return { capsule: undefined, warnings: [{ code: "malformed", message: "Retained state was ignored because it is malformed." }] };
+    }
+    const capsule = {
+        schema_version: "0.1",
+        authority: "shadow",
+        task_id: raw.task_id,
+        acceptance_fingerprint: raw.acceptance_fingerprint,
+        source_manifest: structuredClone(raw.source_manifest),
+        operation_manifest: raw.operation_manifest,
+        validation_history: structuredClone(raw.validation_history),
+        blockers: structuredClone(raw.blockers),
+        next_action: raw.next_action,
+    };
+    const warnings = [];
+    if ("next_evidence_decision" in raw) {
+        if (validDecision(raw.next_evidence_decision))
+            capsule.next_evidence_decision = structuredClone(raw.next_evidence_decision);
+        else
+            warnings.push({ code: "optional_invalid", message: "An optional retained-state decision was ignored." });
+    }
+    if ("admissions" in raw) {
+        if (isBoundedList(raw.admissions)) {
+            const validAdmissions = raw.admissions.filter(validAdmission);
+            if (validAdmissions.length > 0 || raw.admissions.length === 0)
+                capsule.admissions = structuredClone(validAdmissions);
+            if (validAdmissions.length !== raw.admissions.length)
+                warnings.push({ code: "optional_invalid", message: "Invalid retained-state admission receipts were ignored." });
+        }
+        else
+            warnings.push({ code: "optional_invalid", message: "Optional retained-state admission receipts were ignored." });
+    }
+    return { capsule, warnings };
+}

package/dist/index.d.ts

@@ -19,3 +19,5 @@ export type { HandoffDenialReason, OpenCodeEvent, OpenCodeHooks, OpenCodePlugin,
 export { CONSULTATION_CAPABILITIES, CONSULTATION_ROLE_POLICY, MAX_REVIEW_ARTIFACT_BYTES, SOURCE_REVIEW_RISK_TAGS, STRATEGY_TRIGGERS, evaluateReviewAvailability, evaluateReviewGate, evaluateSourceReviewRequirement, isSourceReviewRiskTag, requiresSourceReview, shouldConsultStrategy, validateReviewArtifact, validateReviewVerdict, } from "./core/consultation.js";
 export type { ConsultationAdapter, ConsultationCapability, ConsultationRequest, ConsultationResult, ReviewArtifact, ReviewAvailability, ReviewFinding, ReviewFindingSeverity, ReviewGateInput, ReviewGateResult, ReviewVerdict, ReviewVerdictKind, SourceReviewConsultationRequest, SourceReviewConsultationResult, SourceReviewRequirement, SourceReviewRequirementInput, SourceReviewRiskTag, StrategyConsultationRequest, StrategyConsultationResult, StrategyTrigger, StrategyTriggerInput, UnavailableConsultationResult, ValidationResult, } from "./core/consultation.js";
 export type * from "./core/types.js";
+export { inspectRetainedStateCapsule, MAX_RETAINED_STATE_BYTES, MAX_RETAINED_STATE_ITEMS, MAX_RETAINED_STATE_WARNINGS, RETAINED_STATE_AUTHORITY, RETAINED_STATE_EXTENSION, RETAINED_STATE_SCHEMA_VERSION, } from "./core/retained-state.js";
+export type { AdmissionReceipt, NextEvidenceDecision, RetainedStateCapsule, RetainedStateInspection, RetainedStateWarning, RetainedValidationAttempt, } from "./core/retained-state.js";

package/dist/index.js

@@ -15,3 +15,4 @@ export { SortieDogsPlugin } from "./plugin/index.js";
  */
 export { HandoffDeniedError, InvalidModelTargetError, ModelRoutingDeniedError, isExplicitTaskHandoff, } from "./plugin/index.js";
 export { CONSULTATION_CAPABILITIES, CONSULTATION_ROLE_POLICY, MAX_REVIEW_ARTIFACT_BYTES, SOURCE_REVIEW_RISK_TAGS, STRATEGY_TRIGGERS, evaluateReviewAvailability, evaluateReviewGate, evaluateSourceReviewRequirement, isSourceReviewRiskTag, requiresSourceReview, shouldConsultStrategy, validateReviewArtifact, validateReviewVerdict, } from "./core/consultation.js";
+export { inspectRetainedStateCapsule, MAX_RETAINED_STATE_BYTES, MAX_RETAINED_STATE_ITEMS, MAX_RETAINED_STATE_WARNINGS, RETAINED_STATE_AUTHORITY, RETAINED_STATE_EXTENSION, RETAINED_STATE_SCHEMA_VERSION, } from "./core/retained-state.js";

package/dist/plugin/config.d.ts

@@ -7,6 +7,7 @@ export interface ReflectionConfiguration {
         readonly global: boolean;
     };
     readonly maxInjectedEntries: number;
+    /** Token budget for the dynamic SORTIE_PROCESS_REFLECTIONS heading and persisted entry lines; excludes the governing REFLECTION_POLICY. */
     readonly maxInjectedTokens: number;
 }
 export type ReflectionPolicyInput = Partial<Omit<ReflectionConfiguration, "layers">> & {

package/dist/plugin/continuation.d.ts

@@ -170,10 +170,21 @@ export interface ContinuationHooks {
     sessionIdle(sessionID: string): Promise<void>;
     forgetSession(sessionID: string): void;
 }
+export type ContinuationTransitionType = "continuation.queued" | "continuation.compacted" | "continuation.resumed" | "continuation.not_required";
+export type ContinuationTransitionReason = "continuation-requested" | "compaction-only" | "summarize-accepted" | "prompt-accepted" | "terminal-checkpoint";
+export interface ContinuationTransition {
+    readonly type: ContinuationTransitionType;
+    readonly sessionID: string;
+    readonly epoch: number;
+    readonly reason: ContinuationTransitionReason;
+    readonly attempts: number;
+    readonly resumeAttempts: number;
+}
+export type ContinuationTransitionObserver = (transition: ContinuationTransition) => void;
 /**
  * Build the continuation runtime. Every hook fails closed: an unreadable session, an absent client,
  * or a rejected identity leaves the coordinator exactly where it was, with manual continuation
  * still available to the user.
  */
-export declare function createContinuationHooks(client: ContinuationClient | undefined, directory: string, policySource: ContinuationPolicySource, timings?: ContinuationTimings, localIdentity?: LocalIdentitySource): ContinuationHooks;
+export declare function createContinuationHooks(client: ContinuationClient | undefined, directory: string, policySource: ContinuationPolicySource, timings?: ContinuationTimings, localIdentity?: LocalIdentitySource, transitionObserver?: ContinuationTransitionObserver): ContinuationHooks;
 export {};

package/dist/plugin/continuation.js

@@ -214,9 +214,38 @@ function sessionInfo(response) {
  * or a rejected identity leaves the coordinator exactly where it was, with manual continuation
  * still available to the user.
  */
-export function createContinuationHooks(client, directory, policySource, timings = DEFAULT_TIMINGS, localIdentity) {
+export function createContinuationHooks(client, directory, policySource, timings = DEFAULT_TIMINGS, localIdentity, transitionObserver) {
     const sessions = new Map();
     const warned = new Set();
+    function observeTransition(type, sessionID, state, reason) {
+        try {
+            transitionObserver?.({
+                type,
+                sessionID,
+                epoch: state.rolloverEpoch,
+                reason,
+                attempts: state.attempts,
+                resumeAttempts: state.resumeAttempts,
+            });
+        }
+        catch {
+            // Lifecycle telemetry is best effort and must never affect continuation.
+        }
+    }
+    function observeResumed(sessionID, state, epoch) {
+        if (state.compactedTransitionEpoch !== epoch || state.resumedTransitionEpoch === epoch)
+            return;
+        state.resumedTransitionEpoch = epoch;
+        observeTransition("continuation.resumed", sessionID, state, "prompt-accepted");
+    }
+    function observeCompacted(sessionID, state, epoch) {
+        if (state.compactedTransitionEpoch === epoch)
+            return;
+        state.compactedTransitionEpoch = epoch;
+        observeTransition("continuation.compacted", sessionID, state, "summarize-accepted");
+        if (state.resumeIssuedEpoch === epoch)
+            observeResumed(sessionID, state, epoch);
+    }
     /**
      * A rollover that cannot start is otherwise indistinguishable from a coordinator that never asked
      * for one, so every abort names its own reason exactly once per session.
@@ -374,7 +403,12 @@ export function createContinuationHooks(client, directory, policySource, timings
         const entries = [];
         for (const { index, line } of topLevelProtocolLines(text)) {
             const explicit = /^status:\s*(DONE|BLOCKED|NEED_DECISION)\b/iu.exec(line)?.[1]?.toUpperCase();
-            const status = explicit ??
+            const aliasMatch = /^([✅⛔❓])[ \t]+conclusion:\s*status:\s*(DONE|BLOCKED|NEED_DECISION)\b/iu.exec(line);
+            const aliasStatus = aliasMatch?.[2]?.toUpperCase();
+            const alias = aliasStatus === "DONE" && aliasMatch?.[1] === "✅" ? "DONE" :
+                aliasStatus === "BLOCKED" && aliasMatch?.[1] === "⛔" ? "BLOCKED" :
+                    aliasStatus === "NEED_DECISION" && aliasMatch?.[1] === "❓" ? "NEED_DECISION" : undefined;
+            const status = explicit ?? alias ??
                 (/^✅[ \t]+\*\*DONE\*\*/u.test(line) ? "DONE" :
                     /^⛔[ \t]+\*\*BLOCKED\*\*/u.test(line) ? "BLOCKED" :
                         /^❓[ \t]+\*\*NEED_DECISION\*\*/u.test(line) ? "NEED_DECISION" : undefined);
@@ -384,15 +418,21 @@ export function createContinuationHooks(client, directory, policySource, timings
         }
         return entries;
     }
+    function firstCheckpoint(text) {
+        const firstLine = topLevelProtocolLines(text).find(({ line }) => line.trim().length > 0);
+        return firstLine === undefined
+            ? undefined
+            : checkpointEntries(text).find(({ index }) => index === firstLine.index);
+    }
     function checkpointStatus(text) {
-        return checkpointEntries(text).at(-1)?.status;
+        return firstCheckpoint(text)?.status;
     }
     function terminalCheckpoint(text) {
         const status = checkpointStatus(text);
         return status === "DONE" || status === "NEED_DECISION" || (status === "BLOCKED" && trueBlockerReport(text));
     }
     function trueBlockerReport(text) {
-        const checkpoint = checkpointEntries(text).at(-1);
+        const checkpoint = firstCheckpoint(text);
         if (checkpoint?.status !== "BLOCKED")
             return false;
         return topLevelProtocolLines(text).some(({ line, index }) => index > checkpoint.index &&
@@ -443,7 +483,7 @@ export function createContinuationHooks(client, directory, policySource, timings
     function observeRecoveryReport(state, report) {
         if (state.recoveryObservedRevision === state.turnRevision)
             return state.recoveryRepeatCount;
-        const checkpoint = checkpointEntries(report).at(-1);
+        const checkpoint = firstCheckpoint(report);
         const checkpointLine = checkpoint === undefined
             ? undefined
             : topLevelProtocolLines(report).find(({ index }) => index === checkpoint.index)?.line;
@@ -532,6 +572,7 @@ export function createContinuationHooks(client, directory, policySource, timings
             state.recoverySummaryValidated = false;
             // The accepted prompt now belongs to the host loop, not this rollover request.
             state.active = false;
+            observeResumed(sessionID, state, epoch);
             return true;
         }
         catch (error) {
@@ -608,6 +649,7 @@ export function createContinuationHooks(client, directory, policySource, timings
                 state.promptPending = false;
                 state.compactedRollover = true;
                 state.lastRollover = Date.now();
+                observeCompacted(sessionID, state, operationEpoch);
             }
             if (state.resumeIssuingEpoch === operationEpoch ||
                 state.resumeIssuedEpoch === operationEpoch) {
@@ -694,6 +736,7 @@ export function createContinuationHooks(client, directory, policySource, timings
         if (resume && countAttempt)
             state.attempts += 1;
         const epoch = state.rolloverEpoch;
+        observeTransition("continuation.queued", sessionID, state, resume ? "continuation-requested" : "compaction-only");
         // session.idle can be lost when a one-shot CLI host exits. Keep this zero-delay timer referenced
         // so the rollover reaches the host after the current plugin hook returns but before process exit.
         setTimeout(async () => {
@@ -835,8 +878,11 @@ export function createContinuationHooks(client, directory, policySource, timings
                  * One-shot CLI hosts can exit as soon as the compaction assistant finishes, before the
                  * compacted event or summarize response. Its text-complete hook is the last awaited boundary
                  * where the summary message already exists and a resume prompt can still join the same loop.
-                 */
+                */
                 if (ownedCompactionSummary || trimmed.startsWith(ROLLOVER_TOKEN)) {
+                    if (ownedCompactionSummary) {
+                        observeCompacted(input.sessionID, state, state.rolloverEpoch);
+                    }
                     await arbitrateResume(input.sessionID, state);
                     if (state.resumeIssuedEpoch === state.rolloverEpoch)
                         return;
@@ -850,6 +896,12 @@ export function createContinuationHooks(client, directory, policySource, timings
                         clearTimer(state.stepRecoveryTimer);
                         state.stepRecoveryTimer = undefined;
                         resetRecoveryStall(state);
+                        if (state.notRequiredRevision !== state.turnRevision &&
+                            !output.text.includes(ROLLOVER_MARKER) &&
+                            !output.text.includes(CONTINUATION_MARKER)) {
+                            state.notRequiredRevision = state.turnRevision;
+                            observeTransition("continuation.not_required", input.sessionID, state, "terminal-checkpoint");
+                        }
                     }
                     if (batchCheckpointNeedsContinuation(state.latestCoordinatorReport)) {
                         if (input.allowCheckpointContinuation === false) {
@@ -951,8 +1003,11 @@ export function createContinuationHooks(client, directory, policySource, timings
         },
         async sessionCompacted(sessionID) {
             const state = sessions.get(sessionID);
-            if (state !== undefined)
+            if (state?.pendingRollover === true &&
+                (state.active || state.promptPending || state.compactingEpoch === state.rolloverEpoch)) {
+                observeCompacted(sessionID, state, state.rolloverEpoch);
                 await arbitrateResume(sessionID, state);
+            }
         },
         async compactionAutoContinue(input, output) {
             const state = sessions.get(input.sessionID);

package/dist/plugin/index.d.ts

@@ -10,6 +10,19 @@ export interface OpenCodePluginInput {
     worktree?: string;
     /** The host SDK client. Absent in hosts that construct the plugin without one. */
     client?: SessionMessageReader & RunMetricsClient & ContinuationClient & OpenCodeModelAvailabilityClient & {
+        app?: {
+            log?: (request: {
+                body: {
+                    service: string;
+                    level: "debug" | "info" | "error" | "warn";
+                    message: string;
+                    extra?: Record<string, unknown>;
+                };
+                query?: {
+                    directory?: string;
+                };
+            }) => unknown;
+        };
         tui?: {
             showToast?: (request: {
                 body: {