opencode-swarm 7.167.1 → 7.168.0

package/dist/commands/close/constants.d.ts

@@ -0,0 +1,122 @@
+export declare const NO_RECEIPT_PHASE_CLOSE_SCOPE_DETAIL = "no exact receipt lifecycle scope exists for phase closure";
+export declare const CLOSE_SKILL_REVIEW_TIMEOUT_MS = 120000;
+export declare const CLOSE_REFLECTION_TIMEOUT_MS = 90000;
+/**
+ * Flat-file artifacts to include in the archive bundle.
+ * Each entry is a relative path under .swarm/.
+ *
+ * plan-ledger.jsonl is included so the archive bundle is a self-contained
+ * forensic snapshot of the session: the ledger holds the full audit trail of
+ * task state transitions and snapshot events that plan.json/plan.md don't
+ * preserve.
+ */
+export declare const ARCHIVE_ARTIFACTS: string[];
+/**
+ * Active-state flat files to clean after archiving so future swarms start clean.
+ *
+ * plan.json, plan.md, and plan-ledger.jsonl are all removed so the next /swarm
+ * session starts with a clean slate. The user's original ask for /swarm close
+ * was to "archive plan files so future swarms aren't confused" — leaving a
+ * terminal-state plan.json in place violates that invariant because the next
+ * session's loadPlan() would pick it up as if it were still active.
+ *
+ * CRITICAL: the ledger must also be removed. Without this, loadPlan()'s Step 4
+ * would see no plan.json but a surviving ledger, call replayFromLedger(), and
+ * materialize the CLOSED plan back into plan.json on the next session. The
+ * ledger is a second backing store for the same "terminal-state plan" and
+ * leaving it behind re-enables the exact bug this cleanup is meant to fix.
+ * The archive-first guard below ensures we only delete files we successfully
+ * copied to the archive bundle, so the audit trail is preserved in the bundle.
+ *
+ * knowledge-rejected.jsonl, repo-graph.json, doc-manifest.json,
+ * dark-matter.md, telemetry.jsonl, and swarm.db are
+ * session-generated artifacts that do not persist meaningfully across sessions —
+ * they are recreated on next session init and must be removed to avoid stale-state
+ * interference.
+ *
+ * The SQLite WAL sidecars swarm.db-shm and swarm.db-wal are deliberately NOT in
+ * either list (the archive-first guard would preserve them anyway): since #2483
+ * they are removed immediately AFTER the swarm.db unlink by
+ * removeSqliteSidecarsAfterClose, deliberately reversing #1692. Post-unlink the
+ * sidecar paths are meaningless for future opens (no new opener can attach),
+ * live processes keep their already-open fds so deleting the PATH cannot
+ * corrupt them, and a Windows open-handle collision yields EBUSY which the
+ * helper skips fail-open.
+ *
+ * Note: knowledge.jsonl is intentionally NOT cleaned because it contains cumulative
+ * project knowledge (lessons learned) that should persist across sessions and finalize
+ * cycles. The archive step still creates a backup for safety.
+ * close-summary.md is NOT cleaned because it is written as the final close output
+ * AFTER the clean stage runs. spec.md IS cleaned: it is single-session state coupled
+ * to the plan lifecycle (the plan it produced is removed above), so leaving it behind
+ * makes the next session pick up a stale spec via readEffectiveSpecSync and mis-route
+ * the architect into CLARIFY-SPEC/overwrite prompts. It is archived first (archive-first
+ * guard), so the forensic copy is preserved in the bundle. The earlier "spec.md may not
+ * exist" rationale was wrong — handoff.md is equally optional and is cleaned the same way.
+ * session-reflection.md is a single-session snapshot (not cumulative like
+ * knowledge.jsonl) so it IS cleaned to maintain the clean-slate invariant.
+ * spec-staleness.json and spec-snapshot.md are the same class of single-session
+ * spec-drift state as spec.md. spec-staleness.json is an existence-only gate
+ * checked unconditionally by enforceSpecDriftGate, which hard-blocks the core
+ * write tools (save_plan, update_task_status, phase_complete,
+ * lean_turbo_run_phase, lean_turbo_acquire_locks) with SPEC_DRIFT_BLOCK — a
+ * survivor would block the NEXT session against drift that no longer applies.
+ * spec-snapshot.md is its companion diff source, feeding the mismatch shown in
+ * the SPEC_DRIFT_BLOCK message. Both are archived first (archive-first guard),
+ * then cleaned so the next session starts drift-free.
+ */
+export declare const ACTIVE_STATE_TO_CLEAN: string[];
+/**
+ * Terminal plan-state files that must be removed at finalize UNCONDITIONALLY — even
+ * when archiving them failed — so the next session cannot resurrect the CLOSED plan
+ * (loadPlan Step 1 / replayFromLedger have no terminal-status filter). Kept as a
+ * shared constant so the archive-failure diagnostics and the unconditional removal
+ * below agree on the set; otherwise the "Preserved …" warning would contradict the
+ * removal that always follows for these files.
+ */
+export declare const TERMINAL_STATE_FILES: readonly ["plan.json", "plan-ledger.jsonl", "spec-staleness.json", "spec-snapshot.md"];
+/**
+ * Knowledge-family artifacts whose backing store redirects to a shared link
+ * directory when the worktree is linked (`.swarm/link.json`). A single
+ * worktree's `/swarm close` must NOT archive or delete the cohort-shared store —
+ * peers may still be active, and the shared store is durable with its own
+ * lifecycle (curation/hive-promotion already run on it, link-aware, during
+ * close). When the worktree is NOT linked these are handled normally (local).
+ *
+ * Scope: this set lists exactly the knowledge-family files that close otherwise
+ * archives/cleans — i.e. the intersection with `ARCHIVE_ARTIFACTS` /
+ * `ACTIVE_STATE_TO_CLEAN`. The other redirected files (retractions, counters,
+ * quarantine, unactionable, application, knowledge-events) appear in neither
+ * list, so close never touches them and they need no guard here. Note the two
+ * stages cover different members: the archive-stage guard fires for both
+ * `knowledge.jsonl` and `knowledge-rejected.jsonl` (both in `ARCHIVE_ARTIFACTS`),
+ * while the clean-stage guard is only reachable for `knowledge-rejected.jsonl`
+ * (`ACTIVE_STATE_TO_CLEAN` has no `knowledge.jsonl`).
+ */
+export declare const KNOWLEDGE_FAMILY_ARTIFACTS: Set<string>;
+/**
+ * Artifacts whose absence is a genuine state anomaly (vs the normal "optional,
+ * session-generated, may simply not exist" case). `plan.json`/`plan-ledger.jsonl`
+ * back the authoritative plan state (plan-durability invariant 5); their
+ * absence in a plan-based session warrants a warning. All other artifacts —
+ * including `swarm.db`, which `getProjectDb` creates lazily only when a
+ * DB-backed tool actually runs — are optional: a fresh or plan-free session
+ * legitimately has none of them, and an absent optional artifact is reported
+ * as `source_disposition: 'absent'`, NOT as a failure (issue #2030 item 7).
+ */
+export declare const REQUIRED_ARTIFACTS: Set<string>;
+/**
+ * Active-state directories to archive and clean after archiving.
+ * These contain session-generated data that must be removed so future
+ * swarms start clean. Each entry is a relative path under .swarm/.
+ */
+export declare const ACTIVE_STATE_DIRS_TO_CLEAN: string[];
+/**
+ * STAGE 3: CLEAN
+ *
+ * Removes active-state files and directories that were successfully archived
+ * (archive-first guard), plus stale config-backup/ledger-sibling/SWARM_PLAN/.tmp
+ * artifacts. Resets context.md for the next session. All state mutations are
+ * written back to ctx so the caller can build the close summary.
+ */
+export declare const ACTIVE_STATE_UNLINK_RETRY_DELAYS_MS: readonly [25, 50, 100, 200];

package/dist/commands/close/context.d.ts

@@ -0,0 +1,129 @@
+import type { KnowledgeConfig, PluginConfig } from '../../config/schema';
+import type { SessionReflectionResult } from '../../services/session-reflection';
+import type { SqliteRowCounts } from '../archive-sqlite';
+export interface PlanPhase {
+    id: number;
+    name: string;
+    status: string;
+    tasks: Array<{
+        id: string;
+        status: string;
+        close_reason?: string;
+    }>;
+}
+export interface PlanData {
+    title: string;
+    phases: PlanPhase[];
+}
+export interface CloseCommandOptions {
+    sessionID?: string;
+    skillReviewTimeoutMs?: number;
+}
+export interface CurationCounts {
+    stored: number;
+    /** Issue #2077: surfaced for the reflection knowledge-delta report. */
+    reinforced: number;
+    skipped: number;
+    rejected: number;
+    quarantined: number;
+}
+export interface CloseKnowledgeEntry {
+    created_at?: string;
+}
+export type ArchiveRequiredness = 'required' | 'optional';
+export type ArchiveAttempt = 'not_attempted' | 'succeeded' | 'failed';
+export type ArchiveValidation = 'not_applicable' | 'passed' | 'failed';
+export type ArchiveSourceDisposition = 'absent' | 'retained' | 'removed';
+export interface ArtifactArchiveResult {
+    artifact: string;
+    requiredness: ArchiveRequiredness;
+    attempt: ArchiveAttempt;
+    validation: ArchiveValidation;
+    source_disposition: ArchiveSourceDisposition;
+    method: string;
+    reason_code: string;
+    /** Counts only (no row content), present for validated sqlite snapshots. */
+    row_counts?: SqliteRowCounts;
+    /** Non-sensitive diagnostic. */
+    detail?: string;
+}
+export interface ArchiveStageContext {
+    directory: string;
+    swarmDir: string;
+    config: PluginConfig;
+    warnings: string[];
+}
+export interface CloseStageContext {
+    directory: string;
+    swarmDir: string;
+    planData: PlanData;
+    planExists: boolean;
+    planAlreadyDone: boolean;
+    config: KnowledgeConfig;
+    projectName: string;
+    warnings: string[];
+    closedPhases: number[];
+    closedTasks: string[];
+    sessionStart: string | undefined;
+    isForced: boolean;
+    runSkillReview: boolean;
+    options: CloseCommandOptions;
+    phases: PlanPhase[];
+    inProgressPhases: PlanPhase[];
+    curationSucceeded: boolean;
+    curationResult: CurationCounts | undefined;
+    allLessons: string[];
+    explicitLessons: string[];
+    retroLessons: string[];
+    knowledgeSkillHint: string;
+    skillReviewSummary: string;
+    postMortemSummary: string;
+    sessionReflection: SessionReflectionResult | undefined;
+    hivePromoted: number;
+    sessionKnowledgeCreated: number;
+    fallbackKnowledgeCreated: number;
+    /** Issue #2077: FR-015 dedup drop count (retro lessons dropped as already-known). */
+    dedupDropped: number;
+    /** Issue #2077: false when the dedup knowledge read failed (fail-open). */
+    dedupAvailable: boolean;
+    /** Issue #2077: total retro lessons before dedup. */
+    retroLessonTotal: number;
+    /** Issue #2077: full-auto state computed once, reused at reflection + menu render. */
+    fullAuto: boolean;
+    originalStatuses: Map<string, string>;
+    guaranteeResult: {
+        closedPhaseIds: number[];
+        closedTaskIds: string[];
+    };
+    terminalizationError?: string;
+    archiveResult: string;
+    archivedFileCount: number;
+    archivedActiveStateFiles: Set<string>;
+    archivedActiveStateDirs: Set<string>;
+    archiveFailureReasons: Map<string, string>;
+    /** Structured per-artifact results — single source of truth (issue #2030). */
+    archiveResults: ArtifactArchiveResult[];
+    /** True when the archive STAGE threw wholesale (e.g. mkdir EACCES/ENOSPC). */
+    archiveStageFailed: boolean;
+    timestamp: string;
+    archiveDir: string;
+    archiveSuffix: string;
+    args: string[];
+}
+export interface GitAlignResult {
+    gitAlignResult: string;
+    prunedBranches: string[];
+}
+export interface CleanStageResult {
+    cleanedFiles: string[];
+    configBackupsRemoved: number;
+    swarmPlanFilesRemoved: number;
+    /**
+     * Stale atomic-write temp files MOVED into `.swarm/quarantine/<batch>/`
+     * (issue #2035). Quarantine is a recoverable move with a manifest — the
+     * pre-#2035 blind `.tmp.*` unlink sweep is gone; preserved candidates
+     * (recent/active/tracked/ambiguous) are counted in `residuePreserved`.
+     */
+    residueQuarantined: number;
+    residuePreserved: number;
+}

package/dist/commands/close/db-helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Remove the SQLite WAL sidecars (swarm.db-wal / swarm.db-shm) immediately
+ * after the clean stage unlinks swarm.db (#2483, deliberately reversing the
+ * #1692 preserve decision): once the main db is unlinked the sidecar paths
+ * are meaningless for future opens — no new opener can attach — and live
+ * processes keep their already-open fds, so deleting the PATH cannot corrupt
+ * them. Best-effort and per-file fail-open: ENOENT (already gone) and EBUSY
+ * (Windows open-handle collision) are skipped silently.
+ */
+export declare function removeSqliteSidecarsAfterClose(swarmDir: string): void;

package/dist/commands/close/dry-run.d.ts

@@ -0,0 +1,12 @@
+import type { PlanData } from './context.js';
+/**
+ * Builds the `/swarm finalize --dry-run` report. Purely READ-ONLY: inspects the
+ * plan and the filesystem and describes what a real finalize WOULD do, without
+ * acquiring the finalize lock, creating an archive bundle, deleting any file,
+ * running git, or tearing down session state. (#1692)
+ *
+ * The archive-first guard means the clean stage only removes files it first
+ * archived successfully; this report approximates that by listing existing
+ * clean-set members as "would remove" and notes the approximation.
+ */
+export declare function runFinalizeDryRun(directory: string, swarmDir: string, planData: PlanData, planExists: boolean): Promise<string>;

package/dist/commands/close/finalize-stage.d.ts

@@ -0,0 +1,44 @@
+import type { Plan } from '../../config/plan-schema';
+import { runSessionReflection } from '../../services/session-reflection';
+import { type SkillImproveRequest, type SkillImproveResult } from '../../services/skill-improver';
+import { type CloseTerminalResult } from '../../workflow/close-terminal.js';
+import type { CloseKnowledgeEntry, CloseStageContext, PlanData } from './context.js';
+/**
+ * Close-command wrapper around the exact-task terminal reconciliation service.
+ *
+ * Deliberately NOT named `closePlanTerminalState`: `src/plan/manager.ts` exports a
+ * distinct function by that name (ledger-first phase/projection persistence), which
+ * `reconcileCloseTerminalState` itself calls downstream. Keeping the two identifiers
+ * distinct avoids a same-name collision across close.ts / close-terminal.ts /
+ * plan/manager.ts. The `_internals` key below stays `closePlanTerminalState` so the
+ * existing test seam is unchanged.
+ */
+export declare function reconcileCloseTerminalStateForPlan(directory: string, targetPlan: Plan, options: {
+    actor: string;
+    requestedClosedTaskIds: string[];
+    closedPhaseIds: number[];
+    originalStatuses?: Map<string, string>;
+}): Promise<CloseTerminalResult | undefined>;
+export declare function hardStopTerminalization(ctx: CloseStageContext, message: string): void;
+export declare function runAbortableReflection(input: Parameters<typeof runSessionReflection>[0], timeoutMs: number): Promise<Awaited<ReturnType<typeof runSessionReflection>>>;
+export declare function runAbortableSkillReview(req: SkillImproveRequest, timeoutMs: number): Promise<SkillImproveResult>;
+export declare function normalizeLessonText(text: string): string;
+export declare function countSessionKnowledgeEntries(entries: CloseKnowledgeEntry[], sessionStart: string | undefined, fallbackCount: number): number;
+/**
+ * Guarantee all phases and tasks in a plan are marked complete/closed.
+ * Mutates planData in place. Returns actual IDs of newly closed phases and
+ * tasks so the caller can track only genuinely new closures (idempotent).
+ */
+export declare function guaranteeAllPlansComplete(planData: PlanData): {
+    closedPhaseIds: number[];
+    closedTaskIds: string[];
+};
+/**
+ * STAGE 1: FINALIZE
+ *
+ * Writes retrospectives for in-progress phases (or a session-level retro for
+ * plan-free closes), curates lessons, promotes to hive, runs skill review,
+ * persists terminal plan state, and runs post-mortem. All state mutations are
+ * written back to ctx so the caller can build the close summary.
+ */
+export declare function runFinalizeStage(ctx: CloseStageContext): Promise<void>;

package/dist/commands/close/fs-helpers.d.ts

@@ -0,0 +1,17 @@
+export declare function copyDirRecursiveWithFailures(src: string, dest: string): Promise<{
+    copied: number;
+    failures: string[];
+}>;
+/**
+ * Backward-compatible wrapper that returns only the copied count.
+ * Direct callers (including tests) that expect a number continue to work.
+ * Use copyDirRecursiveWithFailures when per-file failure tracking is needed.
+ */
+export declare function copyDirRecursive(src: string, dest: string): Promise<number>;
+/**
+ * Delete one archived active-state artifact, tolerating the short-lived file
+ * locks Windows antivirus and SQLite sidecars can retain after handle close.
+ * Non-transient errors fail immediately; the retry budget is bounded to
+ * 375 ms so `/swarm close` remains responsive.
+ */
+export declare function unlinkActiveStateFileWithRetry(filePath: string): Promise<void>;

package/dist/commands/close/internals.d.ts

@@ -0,0 +1,55 @@
+import * as fsSync from 'node:fs';
+/** Narrow seam for receipt/plan ordering tests. Wired by the close facade. */
+export declare const closeReceiptLifecycleInternals: {
+    recordPhaseCloseIntent: typeof import("../../hooks/knowledge-receipt-ledger.js").recordPhaseCloseIntent;
+    reconcilePhaseClose: typeof import("../../hooks/knowledge-receipt-ledger.js").reconcilePhaseClose;
+};
+/**
+ * Canonical mutable close-command dependency seam.
+ *
+ * This module intentionally has no imports from the command, agent, state, or
+ * hook graphs. The facade wires concrete implementations after all stage
+ * modules have initialized, so a direct stage import cannot re-enter close.ts
+ * through the command registry (FB-005/FB-006).
+ */
+export declare const _internals: {
+    closeSnapshotCoordinationInitialization: typeof import("../../session/snapshot-coordination-init.js").closeSnapshotCoordinationInitialization;
+    closeRepoMemory: typeof import("../../tools/repo-graph/indexed-storage.js").closeRepoMemory;
+    unlinkActiveStateFileWithRetry: typeof import("./fs-helpers.js").unlinkActiveStateFileWithRetry;
+    unlink: typeof fsSync.promises.unlink;
+    unlinkSidecarSync: typeof fsSync.unlinkSync;
+    sleep: typeof import("../../utils/bun-compat.js").sleep;
+    collectGarbageBestEffort: typeof import("../../utils/bun-compat.js").collectGarbageBestEffort;
+    ACTIVE_STATE_DIRS_TO_CLEAN: string[];
+    countSessionKnowledgeEntries: typeof import("./finalize-stage.js").countSessionKnowledgeEntries;
+    CLOSE_SKILL_REVIEW_TIMEOUT_MS: number;
+    CLOSE_REFLECTION_TIMEOUT_MS: number;
+    detectFullAuto: typeof import("./orchestrator.js").detectFullAuto;
+    guaranteeAllPlansComplete: typeof import("./finalize-stage.js").guaranteeAllPlansComplete;
+    getGitRepositoryStatus: typeof import("../../git/branch.js").getGitRepositoryStatus;
+    resetToMainAfterMerge: typeof import("../../git/branch.js").resetToMainAfterMerge;
+    resetToRemoteBranch: typeof import("../../git/branch.js").resetToRemoteBranch;
+    copyDirRecursive: typeof import("./fs-helpers.js").copyDirRecursive;
+    loadPluginConfigWithMeta: typeof import("../../config/index.js").loadPluginConfigWithMeta;
+    curateAndStoreSwarm: typeof import("../../hooks/knowledge-curator.js").curateAndStoreSwarm;
+    checkHivePromotions: typeof import("../../hooks/hive-promoter.js").checkHivePromotions;
+    runCuratorPostMortem: typeof import("../../hooks/curator-postmortem.js").runCuratorPostMortem;
+    createCuratorLLMDelegate: typeof import("../../hooks/curator-llm-factory.js").createCuratorLLMDelegate;
+    resetSwarmStatePreservingSingletons: typeof import("../../state.js").resetSwarmStatePreservingSingletons;
+    runFinalizeStage: typeof import("./finalize-stage.js").runFinalizeStage;
+    runFinalizeRewardSweep: typeof import("../../memory/finalize-reward-sweep.js").runFinalizeRewardSweep;
+    acquireFinalizeLock: typeof import("./orchestrator.js").acquireFinalizeLock;
+    runArchiveStage: typeof import("./archive-stage.js").runArchiveStage;
+    archiveCloseSummary: typeof import("./orchestrator.js").archiveCloseSummary;
+    runArchiveEvidenceRetention: typeof import("./archive-stage.js").runArchiveEvidenceRetention;
+    runCleanStage: typeof import("./clean-stage.js").runCleanStage;
+    runAlignStage: typeof import("./align-stage.js").runAlignStage;
+    runFinalizeDryRun: typeof import("./dry-run.js").runFinalizeDryRun;
+    archiveEvidence: typeof import("../../evidence/manager.js").archiveEvidence;
+    closePlanTerminalState: typeof import("./finalize-stage.js").reconcileCloseTerminalStateForPlan;
+    endAgentSession: typeof import("../../state.js").endAgentSession;
+    flushAndDrainTelemetry: () => Promise<void>;
+    finalizeContextTelemetry: typeof import("../../context-map/telemetry.js").finalizeContextTelemetry;
+    finalizeCoreEvents: typeof import("../../events/core-events.js").finalizeCoreEventsForClose;
+    finalizeShellAudit: (directory: string) => void;
+};

package/dist/commands/close/orchestrator.d.ts

@@ -0,0 +1,32 @@
+import type { CloseCommandOptions, CloseStageContext } from './context.js';
+export declare function archiveCloseSummary(ctx: Pick<CloseStageContext, 'archiveStageFailed' | 'archiveDir' | 'warnings'>, closeSummaryPath: string, summaryWritten: boolean): Promise<void>;
+/**
+ * Handles /swarm close command - performs full terminal session finalization:
+ * 0. Guarantee: mark all incomplete phases/tasks as closed
+ * 1. Finalize: write retrospectives, produce terminal summary
+ * 2. Archive: create timestamped bundle of swarm artifacts
+ * 3. Clean: clear active-state files that confuse future swarms
+ * 4. Align: safe git alignment to main
+ *
+ * Must be idempotent - safe to run multiple times.
+ */
+export declare function handleCloseCommand(directory: string, args: string[], options?: CloseCommandOptions): Promise<string>;
+/**
+ * Acquire the finalize lock for the close command (FR-012).
+ * Wraps tryAcquireLock with a directory-only API.
+ */
+export declare function acquireFinalizeLock(directory: string): Promise<{
+    acquired: boolean;
+    release?: () => Promise<void>;
+}>;
+/**
+ * Issue #2077: detect full-auto state for the action-menu prompt suppression.
+ * Combines the in-memory session flag (hasActiveFullAuto) with the durable
+ * run state (isFullAutoRunActive reads .swarm/full-auto-state.json) so a
+ * process restart mid-run does not silently re-enable the interactive menu
+ * prompt. The durable check is sync and takes a state lock; if it throws,
+ * fall back to the in-memory flag alone. Caller MUST guard with a defined
+ * sessionID to avoid the cross-session leak (hasActiveFullAuto(undefined)
+ * scans all sessions).
+ */
+export declare function detectFullAuto(directory: string, sessionID: string): boolean;

package/dist/commands/close/wiring.d.ts

@@ -0,0 +1,2 @@
+/** Wire concrete dependencies only after the close facade has loaded its stages. */
+export declare function wireCloseInternals(): void;