peaks-loop 4.0.0-beta.12 → 4.0.0-beta.15

package/dist/cli/commands/hooks-commands.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall } from '../../services/skills/hooks-settings-service.js';

package/dist/cli/commands/ide-commands.js

@@ -1,6 +1,6 @@
 import { detectCurrentIdeModel } from '../../services/ide/current-model-detector.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { listAdapterIds } from '../../services/ide/ide-registry.js';
 export function registerIdeCommands(program, io) {
     const ide = program.command('ide').description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');

package/dist/cli/commands/impact-commands.js

@@ -12,7 +12,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { mustCheckFromReport, runImpactScan } from '../../services/impact/impact-scan-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerImpactCommands(program, io) {
     const impact = program

package/dist/cli/commands/job-commands.js

@@ -1,7 +1,7 @@
 // src/cli/commands/job-commands.ts
 import { join } from 'node:path';
 import { Command } from 'commander';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { JobStateStore } from '../../services/job/job-state-store.js';
 import { JobOrchestrator } from '../../services/job/job-orchestrator.js';

package/dist/cli/commands/legacy-commands.js

@@ -8,7 +8,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { detectLegacy } from '../../services/legacy/legacy-detector.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerLegacyCommands(program, io) {
     addJsonOption(program

package/dist/cli/commands/log-commands.js

@@ -16,7 +16,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { tailLog, listLogFiles } from '../../services/log/log-commands-service.js';
 import { getErrorMessage, printResult, addJsonOption } from '../cli-helpers.js';
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 export function registerLogCommands(program, io) {
     const log = program
         .command('log')

package/dist/cli/commands/loop-commands.js

@@ -25,7 +25,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { openStateDb } from '../../services/skillhub/sqlite-store.js';
 import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError, } from '../../services/share/bundle-writer.js';

package/dist/cli/commands/loop-eval-commands.js

@@ -7,7 +7,7 @@ import { runMonotonicCheck, resolveMonotonicContext } from '../../services/loop/
 import { resolveLoopSpec, persistSpec, buildSpec, lintLoopSpec, lintSpecFile, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from '../../services/loop/spec-service.js';
 import { runLoop, resolveRunContext } from '../../services/loop/run-driver.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 const VALID_EVALUATORS = new Set([
     'karpathy',

package/dist/cli/commands/memory-commands.js

@@ -2,7 +2,7 @@ import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
 import { join } from 'node:path';
 const VALID_KINDS = [

package/dist/cli/commands/migrate-1-4-1-command.js

@@ -6,7 +6,7 @@
  * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
  * `--apply` to actually `rename` the files and remove emptied legacy dirs.
  */
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { addJsonOption } from '../cli-helpers.js';
 import { planMigrate1_4_1, applyMigrate1_4_1 } from '../../services/workspace/migrate-1-4-1-service.js';

package/dist/cli/commands/migrate-v2-10-to-v2-11-command.js

@@ -18,7 +18,7 @@
 import { addJsonOption } from '../cli-helpers.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { planV2ToV11Migration, applyV2ToV11Migration, dryRunV2ToV11Migration } from '../../services/migration/v2-10-to-v2-11-service.js';
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 export function registerMigrateV2ToV11Command(workspace, io) {
     addJsonOption(workspace
         .command('migrate-v2-10-to-v2-11')

package/dist/cli/commands/mut-commands.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { type StrykerInvoker } from '../../services/mut/mut-runner.js';
+import { type StrykerInvoker } from 'peaks-loop-mut';
 import type { ProgramIO } from '../cli-helpers.js';
 export interface MutCommandsOptions {
     readonly invokeStryker: StrykerInvoker;

package/dist/cli/commands/mut-commands.js

@@ -15,11 +15,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { Command } from 'commander';
-import { scanAssertions } from '../../services/mut/assert-scanner.js';
-import { runMutation } from '../../services/mut/mut-runner.js';
-import { buildMutReport } from '../../services/mut/report-builder.js';
-import { createProductionStrykerInvoker } from '../../services/mut/production-stryker.js';
-import { MutReportSchema } from '../../services/mut/types.js';
+import { scanAssertions, runMutation, buildMutReport, createProductionStrykerInvoker, MutReportSchema, } from 'peaks-loop-mut';
 /**
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
  * The mutants-only path does NOT touch the AST scanner; we still need

package/dist/cli/commands/observability-commands.js

@@ -19,7 +19,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { getSessionIdCanonical } from '../../services/session/session-manager.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso, readAllSessionEvents, readSessionEvents } from '../../services/observability/aggregation.js';

package/dist/cli/commands/openspec-commands.js

@@ -6,8 +6,8 @@ import { validateOpenSpecChange } from '../../services/openspec/openspec-validat
 import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
 import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
 import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
-import { runDoctor } from '../../services/doctor/doctor-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { runDoctor } from 'peaks-loop-doctor';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
     if (project === undefined) {

package/dist/cli/commands/perf-audit-commands.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
-import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from '../../services/audit-independent/perf-audit-service.js';
+import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from 'peaks-loop-audit-independent';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 function resolveEnvelope(envelopePath) {
     if (envelopePath === undefined || envelopePath === '-') {
         // Read from stdin

package/dist/cli/commands/perf-commands.js

@@ -1,5 +1,5 @@
 import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerPerfCommands(program, io) {
     const perf = program.command('perf').description('Manage performance baseline scaffolding for the RD stage');

package/dist/cli/commands/polyrepo-commands.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
 import { PolyrepoService } from '../../services/polyrepo/polyrepo-service.js';
 function parseChildren(raw) {
     if (raw === undefined || raw.length === 0)

package/dist/cli/commands/prd-blocks-commands.js

@@ -15,7 +15,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { checkPrdBlocks } from '../../services/prd/prd-blocks-checker.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerPrdBlocksCommands(program, io) {
     // Find existing `prd` top-level command (registered by prd-commands.ts).

package/dist/cli/commands/prd-commands.js

@@ -15,7 +15,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { initHandoff, readHandoff, showHandoff, verifyHandoff, writeHandoff } from '../../services/prd/handoff-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /** Split a comma-separated string into a trimmed, non-empty list.
  *  Empty / undefined input → empty array. */

package/dist/cli/commands/project-commands.js

@@ -4,7 +4,7 @@ import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProje
 import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
 import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
     const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');

package/dist/cli/commands/qa-business-review-commands.js

@@ -15,7 +15,7 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { acceptQaReview, buildEmptyQaReview, deriveQaDecision, QA_BUSINESS_ITEMS, readQaReview, rejectQaReview, scoreQaItem, writeQaReview } from '../../services/qa/qa-business-review-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerQaBusinessReviewCommands(program, io) {
     // G5 commands registered as TOP-LEVEL commands prefixed with `qa-business-`

package/dist/cli/commands/qa-commands.d.ts

@@ -28,7 +28,7 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
-import type { MutReportJson } from '../../services/mut/types.js';
+import { type MutReportJson } from 'peaks-loop-mut';
 export type QaRunOptions = {
     project: string;
     browser?: boolean;

package/dist/cli/commands/qa-commands.js

@@ -27,7 +27,7 @@
  */
 import { join } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { BrowserRestartDetector } from '../../services/qa/browser-restart-detector.js';
 import { BrowserEventLogger } from '../../services/qa/browser-event-logger.js';
 import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
@@ -36,7 +36,7 @@ import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
 import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
 // Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
-import { loadMutReport, mutReportPath } from '../../services/mut/index.js';
+import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
 function buildHeadroomFetcher(sid) {
     return createHeadroomFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,

package/dist/cli/commands/release-commands.js

@@ -19,7 +19,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { hotfixRelease, isReleaseStage, planRelease, readReleaseState, rollbackRelease, transitionRelease, watchWindow, writeReleaseState } from '../../services/release/release-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 const CANARY_PERCENTS = {
     10: 'canary-10',

package/dist/cli/commands/request-commands.js

@@ -4,7 +4,7 @@ import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.
 import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /**

package/dist/cli/commands/retrospective-commands.js

@@ -5,7 +5,7 @@ import { loadRetrospectiveIndex } from '../../services/retrospective/retrospecti
 import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
 import { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 const VALID_RETRO_TYPES = ['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore'];
 const VALID_RETRO_OUTCOMES = ['shipped', 'blocked', 'in-flight', 'cancelled'];

package/dist/cli/commands/reviewer-commands.js

@@ -2,7 +2,7 @@ import { runReviewer, REVIEWER_ID } from '../../services/reviewer/reviewer-servi
 import { loadReviewerConfig } from '../../services/reviewer/reviewer-config.js';
 import { deriveModelFamily } from '../../services/reviewer/model-family.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export function registerReviewerCommands(program, io) {
     const reviewer = program
         .command('reviewer')

package/dist/cli/commands/role-commands.js

@@ -10,7 +10,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { DEFAULT_SENIOR_FE_ROLE, grantPermission, readRoleRegistry, roleHasPermission, upsertRole, writeRoleRegistry } from '../../services/role/role-registry.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerRoleCommands(program, io) {
     const role = program

package/dist/cli/commands/runtime-commands.js

@@ -1,8 +1,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
-import { getErrorMessage } from '../../shared/result.js';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { detectRuntime } from '../../services/runtime/runtime-detector.js';
 import { RuntimeService } from '../../services/runtime/runtime-service.js';
 import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';

package/dist/cli/commands/sc-commands.js

@@ -1,5 +1,5 @@
 import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilityStatus, getScHelpText, recordCommitBoundary, validateArtifactRetention } from '../../services/sc/sc-service.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
 export function registerSCCommands(program, io) {
     const sc = program

package/dist/cli/commands/scan-commands.js

@@ -10,7 +10,7 @@ import { scanApiSurface, formatApiSurfaceMarkdown } from '../../services/scan/ap
 import { scanOrphans, formatOrphanMarkdown } from '../../services/scan/orphan-service.js';
 import { scanKarpathy, formatKarpathyMarkdown } from '../../services/scan/karpathy-service.js';
 import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function parsePositiveInt(value, fallback) {
     if (value === undefined)

package/dist/cli/commands/security-audit-commands.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
-import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/security-audit-service.js';
+import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from 'peaks-loop-audit-independent';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 function resolveEnvelope(envelopePath) {
     if (envelopePath === undefined || envelopePath === '-') {
         // Read from stdin

package/dist/cli/commands/sediment-commands.js

@@ -27,6 +27,7 @@
 import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { join, basename } from "node:path";
 import { SYSTEM_PATH_FORBIDDEN, assertNotSystemPath, resolveSegmentsDir, resolveStateDbPath, resolveBlobsDir, resolveUserBeesDir, resolveUserBeeDir, } from "../../services/sediment/pool-paths.js";
+import { peaksHome } from "../../services/sop/sop-paths.js";
 import { writeBeeManifest } from "../../services/sediment/pool-write.js";
 import { readPool } from "../../services/sediment/pool-read.js";
 import { rebuildIndexFromFs } from "../../services/sediment/pool-rebuild-index.js";
@@ -636,7 +637,15 @@ export function registerSedimentCommands(program, io) {
         .command("sediment <args...>")
         .description("Sediment pool operations (LLM-coordinated; see peaks-maker skill)")
         .action(async (args) => {
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.cwd();
+        // D-018: peaks-loop's `state.db` (loop engineering + bee sediment pool)
+        // lives at PEAKS_HOME-based path, NOT under the project root. The
+        // original `process.env.HOME ?? USERPROFILE ?? process.cwd()` would
+        // resolve `home` to cwd when invoked from a project (e.g.
+        // `peaks skill sediment list` from peaks-loop/), producing
+        // `<project>/.peaks/state.db` — wrong. Per design contract
+        // (peaks-maker SKILL.md §22 + sop-paths.ts §29), the canonical
+        // home is `~/.peaks` (or PEAKS_HOME override for test isolation).
+        const home = peaksHome();
         const r = await runSediment(args, { home });
         // Delegate the JSON rendering AND the process.exitCode side-effect
         // to the shared CLI shim helper (Critical #1 fix). The library

package/dist/cli/commands/share-commands.d.ts

@@ -15,3 +15,22 @@ import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;
+/**
+ * Slice 2026-07-17-D21: peaks sub-agent finalize — LLM-side completion
+ * signal. Without this, dispatch records stay queued forever.
+ *
+ * Contract:
+ *   - LLM MUST call once per dispatched Task, in post-completion branch.
+ *   - --all-stale bulk-marks every queued record for this session (crash recovery).
+ */
+export interface FinalizeOptions {
+    batch?: string;
+    requestId?: string;
+    outcome?: string;
+    error?: string;
+    allStale?: boolean;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+export declare function registerFinalizeCommand(parent: Command, io: ProgramIO): void;

package/dist/cli/commands/share-commands.js

@@ -1,6 +1,7 @@
-import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { resolve } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from '../../services/context/shared-channel.js';
+import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from 'peaks-loop-shared-channel';
 import { writeLogEntry } from '../../services/log/logger.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { summarizeBatchResults } from './sub-agent-shared.js';
@@ -294,3 +295,121 @@ function awaitErrorNextActions(code) {
     }
     return 'See error message; check that --batch matches the dispatch envelope and --timeout is a positive integer ms.';
 }
+export function registerFinalizeCommand(parent, io) {
+    addJsonOption(parent
+        .command('finalize')
+        .description('D21: signal that a dispatched sub-agent has finished (success/failure/cancellation). Pass --all-stale for crash-recovery sweep.')
+        .option('--batch <batchId>', 'batchId from dispatch envelope')
+        .option('--request-id <rid>', 'requestId from dispatch envelope')
+        .option('--outcome <state>', 'done | failed | cancelled (default: done)')
+        .option('--error <msg>', 'error message (when --outcome=failed)')
+        .option('--all-stale', 'bulk-mark every queued record for this session as done')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'override active session id')).action((options) => {
+        void (async () => {
+            const asJson = options.json === true;
+            try {
+                const projectRoot = resolve(options.project ?? process.cwd());
+                const sessionId = options.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+                if (!options.allStale && !options.requestId && !options.batch) {
+                    printResult(io, fail('sub-agent.finalize', 'MISSING_TARGET', 'Pass --request-id or --batch (or --all-stale)', { ok: false }, ['Call finalize after each Task completes.']), asJson);
+                    process.exitCode = 1;
+                    return;
+                }
+                const outcome = (options.outcome ?? 'done');
+                const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
+                const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
+                // map outcome -> (status, outcome)
+                const outcomeMap = {
+                    done: { status: 'done', outcome: 'success' },
+                    failed: { status: 'failed', outcome: 'failed' },
+                    cancelled: { status: 'cancelled', outcome: 'cancelled' },
+                };
+                const mapped = outcomeMap[outcome] ?? outcomeMap['done'];
+                const finalized = [];
+                const skipped = [];
+                const errors = [];
+                const applyOutcome = (recordPath, rid) => {
+                    markCompleted({ recordPath, now: () => new Date(), status: mapped.status, outcome: mapped.outcome, projectRoot });
+                    finalized.push({ recordPath, requestId: rid, status: mapped.status });
+                };
+                if (options.allStale) {
+                    const index = readActiveDispatchIndex(projectRoot, sessionId);
+                    for (const [recordPath, entry] of Object.entries(index)) {
+                        if (entry.status !== 'queued') {
+                            skipped.push({ recordPath, reason: 'status is ' + entry.status });
+                            continue;
+                        }
+                        try {
+                            applyOutcome(recordPath, entry.requestId);
+                        }
+                        catch (e) {
+                            errors.push({ recordPath, error: getErrorMessage(e) });
+                        }
+                    }
+                }
+                else if (options.requestId) {
+                    const fs2 = await import('node:fs');
+                    const path2 = await import('node:path');
+                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
+                    let resolvedPath = null;
+                    if (fs2.existsSync(dir)) {
+                        for (const f of fs2.readdirSync(dir)) {
+                            if (!f.endsWith('.json'))
+                                continue;
+                            const p = path2.join(dir, f);
+                            const r = readRecord(p);
+                            if (r.requestId === options.requestId) {
+                                resolvedPath = p;
+                                break;
+                            }
+                        }
+                    }
+                    if (!resolvedPath) {
+                        printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    try {
+                        applyOutcome(resolvedPath, options.requestId);
+                    }
+                    catch (e) {
+                        errors.push({ recordPath: resolvedPath, error: getErrorMessage(e) });
+                    }
+                }
+                else {
+                    const fs2 = await import('node:fs');
+                    const path2 = await import('node:path');
+                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
+                    if (fs2.existsSync(dir)) {
+                        for (const f of fs2.readdirSync(dir)) {
+                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
+                                continue;
+                            const p = path2.join(dir, f);
+                            const r = readRecord(p);
+                            if (r.batchId !== options.batch)
+                                continue;
+                            if (r.status !== 'queued') {
+                                skipped.push({ recordPath: p, reason: 'status is ' + r.status });
+                                continue;
+                            }
+                            try {
+                                applyOutcome(p, r.requestId);
+                            }
+                            catch (e) {
+                                errors.push({ recordPath: p, error: getErrorMessage(e) });
+                            }
+                        }
+                    }
+                }
+                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], errors.length > 0 ? ['Re-run after fixing.'] : ['All targeted records transitioned out of queued.']), asJson);
+                if (errors.length > 0)
+                    process.exitCode = 1;
+            }
+            catch (error) {
+                printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, ['Inspect the error.']), asJson);
+                process.exitCode = 1;
+            }
+        })();
+    });
+}

package/dist/cli/commands/skill-conformance-commands.js

@@ -6,7 +6,7 @@
  */
 import { auditSkillConformance } from '../../services/skills/skill-conformance-service.js';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export function registerSkillConformanceCommands(program, io) {
     program
         .command('skills:audit-conformance')

package/dist/cli/commands/skill-loop-engineering-readiness-commands.js

@@ -36,7 +36,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { lintSkillLoopEngineeringReadiness, } from '../../services/standards/loop-engineering-readiness-lint.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export const LOOP_ENGINEERING_READINESS_CATEGORY = 'loop-engineering-readiness';
 /**
  * Resolve the SKILL.md file path from a `--path <skill-dir>` value.

package/dist/cli/commands/skill-search-commands.js

@@ -1,5 +1,5 @@
 import { searchSkills, SkillSearchInputSchema } from '../../services/skill/skill-search-service.js';
-import { getErrorMessage } from '../../shared/result.js';
+import { getErrorMessage } from 'peaks-loop-shared/result';
 /**
  * Validate the raw CLI flags, call the service, and emit a JSON
  * envelope on stdout. Errors flow through stderr + non-zero exit

package/dist/cli/commands/slice-commands.js

@@ -7,7 +7,7 @@ import { decomposeSlicesWithBenchmark } from '../../services/slice/slice-benchma
 import { pickSlicesInteractive } from '../../services/slice/slice-pick-service.js';
 import { decompose as multiPassDecompose } from '../../services/slice/multi-pass-orchestrator.js';
 import { readResult as readDecompositionResult, writeResult as writeSchemaResult } from '../../services/slice/schema-router.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerSliceCommands(program, io) {
     const slice = program.command('slice').description('Slice lifecycle: check (boundary), decompose (PRD -> 6-stage algorithm), ' +

package/dist/cli/commands/slice-integrate-commands.js

@@ -10,7 +10,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { integrateSlices } from '../../services/slice/slice-integration.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 function loadContractsForSlices(projectRoot, sessionId, sliceIds) {
     const dir = resolve(projectRoot, '.peaks', '_runtime', sessionId, 'dispatch', 'contracts');

package/dist/cli/commands/slice-review-commands.js

@@ -21,7 +21,7 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { acceptReview, buildEmptySliceReview, DEFAULT_REVIEW_ITEMS, deriveDecision, readSliceReview, rejectReview, renderChecklist, scoreItem, writeSliceReview } from '../../services/slice/slice-review-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerSliceReviewCommands(program, io) {
     // G1 commands registered as TOP-LEVEL commands prefixed with `slice-review-`

package/dist/cli/commands/smoke-commands.js

@@ -18,7 +18,7 @@ import { readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { addCriticalPath, CRITICAL_PATH_SOURCES, EMPTY_SMOKE_STATE, isCriticalPathSource, makeCriticalPathId, readSmokeState, recordRun, summarizeState, writeSmokeState } from '../../services/smoke/smoke-paths-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 const RUN_STATUSES = ['pending', 'pass', 'fail'];
 export function registerSmokeCommands(program, io) {