@mstar-harness/engine 3.8.3 → 3.9.1

package/dist/evidence.d.ts

@@ -0,0 +1,174 @@
+import type { GateResult } from "./core.js";
+import type { SddExecutionContext } from "./sdd.js";
+export type EvidenceEnvironmentKey = "CI" | "NODE_ENV" | "TZ" | "LANG";
+export type EvidenceInputSpec = {
+    path: string;
+    kind: "file" | "directory";
+    purpose: "source" | "test" | "fixture" | "config" | "dependency";
+};
+export type EvidenceCoverage = {
+    acIds: string[];
+    behavior: string;
+    declaration: "reviewed" | "unknown";
+    sourceRationale: string;
+    dependencyRationale: string;
+    runtimeRationale: string;
+    environmentRationale: string;
+};
+export type EvidenceLimits = {
+    timeoutMs: number;
+    maxLogBytesPerStream: number;
+    maxInputBytes: number;
+    maxInputEntries: number;
+    maxInputMs: number;
+    maxSnapshotBytes: number;
+};
+export type EvidenceCaptureRequest = {
+    context: SddExecutionContext;
+    taskId: string;
+    coverage: EvidenceCoverage;
+    inputs: EvidenceInputSpec[];
+    environmentKeys: EvidenceEnvironmentKey[];
+    timeoutMs?: number;
+};
+export type EvidenceInputEntry = {
+    path: string;
+    kind: "file" | "directory" | "symlink" | "missing" | "unknown";
+    sha256: string | null;
+    bytes: number | null;
+    executable: boolean | null;
+    linkText: string | null;
+    resolvedRelativePath: string | null;
+    error: string | null;
+};
+export type EvidenceToolFingerprint = {
+    requested: string;
+    resolvedPath: string | null;
+    sha256: string | null;
+    bytes: number | null;
+    platform: string;
+    arch: string;
+    runnerRuntimeVersion: string;
+    error: string | null;
+};
+export type EvidenceInputSnapshot = {
+    repoCommonDir: string | null;
+    head: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+    dirtyStatusSha256: string | null;
+    entries: EvidenceInputEntry[];
+    tool: EvidenceToolFingerprint;
+    environment: Partial<Record<EvidenceEnvironmentKey, string | null>>;
+    unknowns: string[];
+    stable: boolean;
+    digest: string;
+};
+export type EvidenceOutcome = {
+    kind: "running";
+} | {
+    kind: "exit";
+    code: number;
+} | {
+    kind: "signal";
+    signal: string;
+} | {
+    kind: "timeout";
+} | {
+    kind: "interrupted";
+    signal: "SIGINT" | "SIGTERM";
+} | {
+    kind: "spawn-error";
+    code: string;
+};
+export type EvidenceLog = {
+    path: "stdout.log" | "stderr.log";
+    bytes: number;
+    sha256: string | null;
+    truncated: boolean;
+};
+export type SddEvidenceRecord = {
+    schema: "mstar.sdd-evidence/v1";
+    producer: {
+        name: "mstar-harness";
+        version: string;
+    };
+    runId: string;
+    request: EvidenceCaptureRequest;
+    command: {
+        argv: string[];
+        cwd: string;
+    };
+    startedAt: string;
+    endedAt: string | null;
+    state: "running" | "finished";
+    outcome: EvidenceOutcome;
+    before: EvidenceInputSnapshot;
+    after: EvidenceInputSnapshot | null;
+    logs: {
+        stdout: EvidenceLog;
+        stderr: EvidenceLog;
+    };
+    limits: EvidenceLimits;
+    captureErrors: string[];
+    counts: null;
+};
+export type EvidenceArtifactFact = {
+    path: "stdout.log" | "stderr.log";
+    state: "regular" | "missing" | "symlink" | "other" | "unreadable";
+    bytes: number | null;
+    sha256: string | null;
+};
+export type EvidenceExpectation = {
+    planId: string;
+    taskId: string;
+    runId: string;
+};
+export type EvidenceAssessment = {
+    integrity: GateResult;
+    outcome: "passed" | "failed" | "incomplete" | "unknown";
+    applicability: "not-assessed" | "candidate" | "changed" | "uncertain";
+    coverage: "review-required";
+    changedInputs: string[];
+    reasons: string[];
+};
+/**
+ * SHA-256 over the canonical serialization of the snapshot projection.
+ * Expects the typed, shape-bounded snapshot; out-of-contract direct input
+ * (missing fields, cycles, non-JSON values) throws `TypeError` rather than
+ * fabricating a digest. Public unknown-record validators catch that as an
+ * `evidence.schema` violation. Never call full record validation from here.
+ */
+export declare function evidenceInputDigest(snapshot: EvidenceInputSnapshot): string;
+/**
+ * Validate one retained evidence record. Malformed unknown input yields
+ * `GateResult` violations (all severity high) and never throws. Checks the
+ * exact property sets at every object level, the fixed v1 collection
+ * limits, state/outcome/endedAt consistency, log slot literals and caps,
+ * entry/tool/environment fact rules, command cwd agreement with the
+ * recorded context, and recomputation of every snapshot digest.
+ */
+export declare function validateSddEvidenceRecord(record: unknown): GateResult;
+/**
+ * Verify that the retained artifacts match the recorded facts and that the
+ * record is complete: exactly one regular-file fact per fixed log slot,
+ * exact bytes and hash, finished state, non-truncated logs and no capture
+ * errors. A completed nonzero exit with complete artifacts verifies as
+ * valid failure evidence — integrity is independent of the recorded
+ * outcome. Gate codes are fixed; no hard-blocked override exists.
+ */
+export declare function verifySddEvidence(record: unknown, artifacts: readonly EvidenceArtifactFact[], expected: EvidenceExpectation): GateResult;
+/**
+ * Assess whether one retained evidence bundle still applies to the current
+ * declared inputs. Read-only: no child execution, discovery, version probe
+ * or write. The four outputs stay separate — a damaged log or an identity
+ * mismatch never rewrites the recorded outcome, and a failed or incomplete
+ * run can never become a reuse candidate. `changedInputs` discloses sorted
+ * known differing paths (or `$tool`/`$environment`/`$repository` labels)
+ * even when an earlier rule already forces uncertainty; no-target mode
+ * returns an empty list. Digest equality is consulted only after the
+ * preceding first-match checks, so an unknown marker never becomes a false
+ * changed/candidate result. A malformed target snapshot is downgraded to
+ * the unknown lane instead of throwing.
+ */
+export declare function assessSddEvidenceReuse(record: unknown, artifacts: readonly EvidenceArtifactFact[], expected: EvidenceExpectation, target?: EvidenceInputSnapshot): EvidenceAssessment;

package/dist/index.d.ts

@@ -24,7 +24,12 @@
  * gate core (target classification + content/edit validation + reason
  * formatting, shared by the omp and ZCode host gates), and `skill-authoring`
  * lints frontmatter +
- * 5-question bodies and resolves skill-relative asset paths.
+ * 5-question bodies and resolves skill-relative asset paths, and
+ * `cleanup` is the pure worktree/branch cleanup planner (immutable facts
+ * in, stable `cleanup.*` remove/keep/refuse decisions out), and `evidence`
+ * is the pure SDD test-evidence contract (record schema validation,
+ * artifact verification, input fingerprinting and reuse assessment —
+ * values in, decisions out).
  */
 export type { GateResult, Severity, ValidationResult } from "./core.js";
 export { DSH_LLM_FALLBACKS_VERSION, SEVERITY_ORDER, applyEnforcement, readHarnessVersion, readJson, resolveProjectRoot, writeJson } from "./core.js";
@@ -36,16 +41,20 @@ export type { PlanRow, ResidualEntry, StatusDoc, StatusV2Doc, WorkflowEntry, } f
 export { normalizeSeverity, registerWorkflow, resolveCompassEnforcement, resolveMstarcEnforcement, resolveRepoEnforcement, unregisterWorkflow, validatePlanRow, validateResidual, validateStatus, validateStatusV2, validateWorkflowEntry, } from "./status.js";
 export type { ClaimLeaseFields, ExecutionLease, ExecutionLeaseLocations, IntegrationMergeLease, LeaseTransition, LeaseVerifyResult, } from "./lease.js";
 export { canSteal, claimLease, planExecutionLeaseLocations, releaseLease, sameHolderResume, validateExecutionLease, validateIntegrationMergeLease, verifyPlanExecutionLease, withStatusWriteLock, } from "./lease.js";
-export type { WorkflowBranchAnchors, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, } from "./workflow.js";
-export { WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
+export type { CloseWorkflowOptions, WorkflowBranchAnchors, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, WorkflowSnapshotRead, } from "./workflow.js";
+export { closeWorkflow, isTerminalSnapshot, LEGACY_WORKTREE_PATH_CODE, WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, readWorkflowSnapshot, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
+export type { CleanupDecision, CleanupFacts, CleanupTarget, CleanupTargetKind, } from "./cleanup.js";
+export { planWorktreeCleanup } from "./cleanup.js";
+export type { EvidenceArtifactFact, EvidenceAssessment, EvidenceCaptureRequest, EvidenceCoverage, EvidenceEnvironmentKey, EvidenceExpectation, EvidenceInputEntry, EvidenceInputSnapshot, EvidenceInputSpec, EvidenceLimits, EvidenceLog, EvidenceOutcome, EvidenceToolFingerprint, SddEvidenceRecord, } from "./evidence.js";
+export { assessSddEvidenceReuse, evidenceInputDigest, validateSddEvidenceRecord, verifySddEvidence, } from "./evidence.js";
 export type { AssignmentBranchForms, AssignmentFields, ComposeDispatchGateOptions, ComposeDispatchGateResult, DefaultBranchOptions, EnforcementFlag, EnforcementSource, ExecutionModeToNOptions, ExecutionModeToNResult, ValidateAssignmentFieldsOptions, } from "./dispatch.js";
 export { antiRecursionPrecheck, assertDefaultBranchProtected, assertTriIdentity, assignmentHeaderRegion, composeDispatchGate, executionModeToN, isReadOnlyAssignmentRole, parseAssignmentBranchForms, parseAssignmentFields, parseBranchPolicyDirectOnBranch, parseEnforcementFlag, validateAssignmentFields, } from "./dispatch.js";
-export type { BranchProbeOptions, L1PreDispatchInput, L2PreDispatchInput, QcAlignmentAssignment, QcSnapshotAssignment, WorktreeTrack, } from "./worktree.js";
-export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, isDistinctCheckout, l1PreDispatchCheck, l2PreDispatchCheck, probeCheckoutRoot, singleReviewSnapshot, } from "./worktree.js";
+export type { BranchProbeOptions, L1PreDispatchInput, L2PreDispatchInput, MainWorktreeInfo, QcAlignmentAssignment, QcSnapshotAssignment, WorktreeTrack, } from "./worktree.js";
+export { assertBranchAlignment, assertControlVsFeaturePath, assertMainWorktreeResidency, assertQcAlignment, isDistinctCheckout, l1PreDispatchCheck, l2PreDispatchCheck, probeCheckoutRoot, readMainWorktree, singleReviewSnapshot, } from "./worktree.js";
 export type { ImplementerSessionLedger, ReviewPackageOptions, SddAction, SddActionKind, SddExecutionContext, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
 export { GIT_CAPTURE_MAX_BYTES, SddScriptError, assertBaseSha, checkSddAction, implementerSessionStickyRules, readProgressLedger, resolveSddExecutionContext, reviewPackage, runInSddContext, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
-export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
-export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
+export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, SnapshotDoc, } from "./iteration.js";
+export { assertIndexRowObligations, evaluatePhaseGate, evaluatePostMergeClose, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
 export type { AppendProjectRegisterEntriesOpts, CloseProjectRegisterEntryOpts, FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
 export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, appendProjectRegisterEntries, closeProjectRegisterEntry, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
 export type { HarnessDocKind, ValidateStatusWriteDocOptions } from "./gates.js";
@@ -70,3 +79,5 @@ export type { MergeClass, MstarReviewFinding, MstarReviewV1, PrReportTarget, PrR
 export { MERGE_CLASSES, PR_REVIEW_TIER_BUDGETS, PR_VERDICTS, REVIEW_EMOJI, computePrTally, pickReviewBranchName, planReviewPost, preflightChangeset, prReviewReportPath, prReviewSeatPrompt, prReviewSizing, resolvePrReviewTier, synthesizeReview, validateFindingDoc, validateMstarReviewV1, validatePrReviewReport, } from "./prreview.js";
 export type { ArtifactDoc, ArtifactKind, ArtifactRef, ArtifactStore } from "./store.js";
 export { assertFsStorePath, createFsStore, getArtifactStore, loadStoreModule, resolveArtifactPath, setArtifactStore } from "./store.js";
+export { collectActiveLifecycleBranches, scanActiveLifecycleBranches, type ActiveLifecycleScan } from "./lifecycle-branches.js";
+export { WorkflowSnapshotValidationError } from "./workflow.js";

package/dist/iteration.d.ts

@@ -6,11 +6,13 @@ import type { GateResult, ValidationResult } from "./core.js";
  * verbatim () — `findPlanRow` accepts `id` or `plan_id`.
  *
  * Deliberate decoupling: this is a loose LOCAL re-declaration,
- * NOT an import of `WorkflowSnapshot` from workflow.ts. This module only
- * reads `plans[].status`; importing the full schema would add a module edge
- * to workflow.ts (which imports status.ts, which workflow.ts cycles back
- * through — the call-time-safe loop family stays static-edge-free this
- * way). Keep this shape in sync manually when the snapshot schema changes.
+ * NOT an import of `WorkflowSnapshot` from workflow.ts. The loose phase-gate
+ * reads (`evaluatePhaseGate`) only touch `plans[].status`, so the full
+ * schema stays out of those call paths. The Phase-6 gate
+ * (`evaluatePostMergeClose`) DOES consume the strict T1 validator directly
+ * (static edge iteration → workflow; workflow's closure never imports this
+ * module, so no cycle is created). Keep this shape in sync manually when
+ * the snapshot schema changes.
  */
 export type SnapshotDoc = {
     plans?: unknown;
@@ -93,6 +95,34 @@ export declare function validateCompassFrontmatter(doc: unknown): GateResult;
  * `prBaseBranch`) come from the caller via `opts`.
  */
 export declare function evaluatePhaseGate(snapshotDoc: SnapshotDoc, compassDoc: CompassDoc, opts?: PhaseGateOptions): PhaseGateResult;
+/**
+ * Phase 6 post-merge close local-state gate (phase-6-post-merge-close.md
+ * §6.4 + Evidence): verifies the checkable post-close state — the workflow
+ * snapshot is a valid v3 document (T1 `validateWorkflowSnapshot`, with the
+ * single legacy `control_worktree_path` alias non-blocking exactly as the
+ * canonical reader accepts and migrates it) in a
+ * terminal status (completed | failed | stopped, T1 `isTerminalSnapshot`),
+ * no `plans[].execution_lease` or top-level `integration_merge_lease`
+ * survived the close, and the root `status.json` validates as a v2 registry
+ * (`validateStatusV2`, structure-only) and no longer registers the
+ * workflow (removal-at-terminal).
+ *
+ * Deliberately does NOT verify remote merge evidence or physical cleanup —
+ * the gate only reads local state. An invalid/unreadable ROOT — any
+ * `validateStatusV2` failure (non-v2 version, missing `updated_at`,
+ * malformed `workflows[]` or entries) — is a
+ * violation (`PHASE6_INVALID_ROOT`): it is not proof of the entry's
+ * absence. The lease probe runs on terminal documents only — mid-flight
+ * leases on a running lifecycle are legitimate and the actionable code is
+ * `PHASE6_NOT_TERMINAL`.
+ *
+ * Pure and additive: consumes T1's validators unchanged and does not touch
+ * `evaluatePhaseGate` / `PhaseGateResult` (Phase 2–5 exit codes stay
+ * intact). Stable machine codes: `PHASE6_NOT_TERMINAL`,
+ * `PHASE6_ROOT_ENTRY_PRESENT`, `PHASE6_DANGLING_LEASE`,
+ * `PHASE6_INVALID_SNAPSHOT`, `PHASE6_INVALID_ROOT`.
+ */
+export declare function evaluatePostMergeClose(snapshotDoc: SnapshotDoc, rootDoc: unknown): GateResult;
 /**
  * §5.1a push-cadence probe (HARD): never push the PR head while required CI
  * is still queued/in_progress or an AI/bot review wave is running. Pure

package/dist/lifecycle-branches.d.ts

@@ -0,0 +1,17 @@
+import { type ValidationResult } from "./core.js";
+/** Collect ownership, including retained L2 tracks; base/target are not ownership. */
+export declare function collectActiveLifecycleBranches(snapshots: readonly Record<string, unknown>[]): string[];
+export type ActiveLifecycleScan = {
+    kind: "ok";
+    branches: string[];
+    notes: ValidationResult[];
+} | {
+    kind: "refusal";
+    code: string;
+    detail: string;
+};
+/** Read all other registered active snapshots through the canonical reader.
+ * Missing register means no siblings; malformed register or unreadable sibling
+ * refuses. Governing snapshot is supplied by the caller, never read twice.
+ */
+export declare function scanActiveLifecycleBranches(harnessDir: string, governingWorkflowId: string | null): ActiveLifecycleScan;

package/dist/sdd.d.ts

@@ -12,7 +12,7 @@ export declare class SddScriptError extends Error {
  * usage plus the harness-root override (plan finding 2026-08-08).
  */
 export type SddWorkspaceOptions = {
-    /** Control worktree repo root — CLI 2nd arg / `MSTAR_CONTROL_ROOT`. */
+    /** Main worktree repo root — CLI 2nd arg / `MSTAR_CONTROL_ROOT`. */
     controlRoot?: string;
     /** Explicit harness root — `MSTAR_HARNESS_DIR` / `--harness-dir`. */
     harnessDir?: string;
@@ -63,19 +63,24 @@ export declare const GIT_CAPTURE_MAX_BYTES: number;
  * Resolve and ensure `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/` (prints
  * the absolute path). Resolution order:
  *
- * 1. fail-closed FIRST: a linked worktree without a control root never
- * resolves or creates any SDD tree under the feature checkout (refuses a
- * second SDD tree; no override or probe may bypass this guard);
- * 2. explicit harness-root override (`opts.harnessDir` / `MSTAR_HARNESS_DIR`)
- * — plan finding 2026-08-08: covers repos the status.json probe misses;
- * resolved relative to the established root;
- * 3. `.mstarc` `[config] harness_dir` at `root` (repo-declared root;
- * resolved against the config file's directory);
- * 4. `status.json` probe at root (`.mstar` → `.agents`);
- * 5. fallback: existing `.mstar`/`.agents` dir, else `.mstar`.
- *
- * `controlRoot` (CLI 2nd arg / `MSTAR_CONTROL_ROOT`) pins `root` to the
- * control worktree instead of the cwd's git top-level.
+ * 1. Git-derived MAIN discovery FIRST (fail-closed): the process-SSOT
+ *    control root is the MAIN worktree (`readMainWorktree` — the first
+ *    `git worktree list --porcelain -z` record). From a linked checkout the
+ *    first record still reaches main; a failed/unavailable probe (null)
+ *    refuses BEFORE any harness resolution or mkdir — nothing is written.
+ * 2. An explicit `controlRoot` (CLI 2nd arg / `MSTAR_CONTROL_ROOT`) must BE
+ *    the main worktree when Git is available — an integration/foreign
+ *    linked checkout is refused, never silently redirected; explicit
+ *    non-Git standalone roots are preserved;
+ * 3. explicit harness-root override (`opts.harnessDir` / `MSTAR_HARNESS_DIR`)
+ *    — resolved relative to the established main root;
+ * 4. `.mstarc` `[config] harness_dir` at the main root (repo-declared root;
+ *    resolved against the config file's directory);
+ * 5. `status.json` probe at the main root (`.mstar` → `.agents`);
+ * 6. fallback: existing `.mstar`/`.agents` dir under the main root, else
+ *    `.mstar`;
+ * 7. the resolved harness dir must not redirect the process SSOT into a
+ *    linked/foreign Git checkout — refused before any mkdir/write.
  */
 export declare function sddWorkspace(planId: string, opts?: SddWorkspaceOptions): string;
 /**
@@ -242,7 +247,9 @@ export type SddActionKind = "source" | "artifact" | "launch";
  * `workflows[]`; a retained terminal snapshot never satisfies lease
  * enforcement, and a plan claimed by multiple active workflows fails
  * closed), its lease is verified (`verifyPlanExecutionLease`) and the
- * L1 checklist runs (`l1PreDispatchCheck` with the control checkout);
+ * L1 checklist runs (`l1PreDispatchCheck` with the Git-derived MAIN
+ * worktree, the governing snapshot's integration topology, the recorded
+ * residency expectation and the active lifecycle-branch ownership set);
  * the context must then match the verified lease exactly. Without an
  * active lease (no row, or a non-InProgress row without lease), the
  * standalone branch policy applies (`assertBranchAlignment`) — an

package/dist/status.d.ts

@@ -58,6 +58,7 @@ export type PlanRow = {
     title?: unknown;
     file?: unknown;
     status?: unknown;
+    /** Opaque plan metadata; metadata.track_branches retains active L2 Assignment working branches. */
     metadata?: unknown;
     execution_lease?: unknown;
     [key: string]: unknown;

package/dist/workflow.d.ts

@@ -1,4 +1,4 @@
-import type { GateResult } from "./core.js";
+import type { GateResult, ValidationResult } from "./core.js";
 import { type IntegrationMergeLease } from "./lease.js";
 import { type PlanRow } from "./status.js";
 /** Snapshot file name inside `workflows/<id>/` ( — writer contract). */
@@ -33,6 +33,14 @@ export type WorkflowBranchAnchors = {
  * per-row `execution_lease` stays on the row, `integration_merge_lease` is
  * top-level.
  *
+ * Integration worktree path: the canonical member is
+ * `integration_worktree_path` — the dedicated integration checkout, on
+ * `branch.integration`, distinct from the main worktree. The v1
+ * `control_worktree_path` key has NO canonical member: legacy-only
+ * documents stay readable through `readWorkflowSnapshot` (in-memory
+ * normalization + medium migration diagnostic); writers emit only the
+ * canonical shape — no dual writer.
+ *
  * Notes dual-home SSOT: a plan row's `notes` array is the
  * LEGACY VERBATIM copy preserved at migrate time — the RUNTIME ledger is
  * `notes.jsonl` in the workflow dir (`migrate.ts` NOTES_LEDGER_FILE). New
@@ -52,7 +60,7 @@ export type WorkflowSnapshot = {
     execution_policy?: WorkflowExecutionPolicy;
     integration_merge_lease?: IntegrationMergeLease;
     branch?: WorkflowBranchAnchors;
-    control_worktree_path?: string;
+    integration_worktree_path?: string;
     legacy_metadata?: Record<string, unknown>;
     compass_ref?: string;
 };
@@ -63,11 +71,48 @@ export type WorkflowSnapshot = {
  * `execution_lease` shape delegated to `validateExecutionLease`,
  * `integration_merge_lease` shape delegated to
  * `validateIntegrationMergeLease`, `execution_policy` keys accepted-but-
- * opaque. Terminal invariant: `status` ∈ completed|failed|stopped ⇒
- * `ended_at` present AND no row carries `execution_lease` AND no
- * `integration_merge_lease` (no dangling leases).
+ * opaque. Integration worktree path: the canonical member is
+ * `integration_worktree_path`; the v1 `control_worktree_path` key is a
+ * read-only alias whose presence keeps this STRICT validation a failing
+ * gate carrying the medium `workflow.snapshot.legacy-control-worktree-path`
+ * migration diagnostic (read acceptance is not write permission — the
+ * canonical reader is the only consumer that normalizes it, in memory);
+ * both keys present is `workflow.snapshot.conflicting-worktree-paths`
+ * (high), even when the values are equal. Terminal invariant: `status` ∈
+ * completed|failed|stopped ⇒ `ended_at` present AND no row carries
+ * `execution_lease` AND no `integration_merge_lease` (no dangling leases).
  */
 export declare function validateWorkflowSnapshot(doc: unknown): GateResult;
+/** Machine code of the v1 read-alias migration diagnostic (`readWorkflowSnapshot`). */
+export declare const LEGACY_WORKTREE_PATH_CODE = "workflow.snapshot.legacy-control-worktree-path";
+/**
+ * Result of the canonical snapshot read: the validated snapshot plus the
+ * non-blocking diagnostics collected while reading (currently only the
+ * `workflow.snapshot.legacy-control-worktree-path` migration diagnostic for
+ * v1-shaped documents). A read with diagnostics is NOT write permission —
+ * writers keep strict validation and emit only the canonical shape.
+ */
+export type WorkflowSnapshotRead = {
+    snapshot: WorkflowSnapshot;
+    diagnostics: ValidationResult[];
+};
+/**
+ * Canonical snapshot reader (`{WORKFLOW_DIR}/<id>/snapshot.json`): reads
+ * `dir/snapshot.json`, validates the raw document, normalizes the single
+ * permitted legacy alias (`control_worktree_path` →
+ * `integration_worktree_path`) IN MEMORY and returns its medium migration
+ * diagnostic separately. Any other validation violation refuses the read
+ * (throw) — read acceptance extends only to the migration diagnostic, so
+ * this never weakens the strict writer gate. Performs no writes: the
+ * source file's bytes are never touched; legacy snapshots migrate on their
+ * next authorized read-modify-write through the canonical writer. Missing
+ * files, malformed JSON, and non-object documents throw.
+ */
+export declare class WorkflowSnapshotValidationError extends Error {
+    readonly violations: ValidationResult[];
+    constructor(message: string, violations: ValidationResult[]);
+}
+export declare function readWorkflowSnapshot(dir: string): WorkflowSnapshotRead;
 /**
  * Write a workflow snapshot as a whole-rewrite of `dir/snapshot.json` under
  * `withStatusWriteLock(snapshotPath)` ( — the `.status-write.lockdir`
@@ -84,3 +129,13 @@ export declare function validateWorkflowSnapshot(doc: unknown): GateResult;
  * `setArtifactStore(createFsStore(root))` first.
  */
 export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string): Promise<void>;
+/** Terminal enum predicate only; callers validate document shape separately. */
+export declare function isTerminalSnapshot(doc: WorkflowSnapshot): boolean;
+export type CloseWorkflowOptions = {
+    endedAt: string;
+};
+/**
+ * Complete the latest snapshot under its write lock. Never releases leases.
+ * A valid terminal snapshot is returned unchanged, including failed/stopped.
+ */
+export declare function closeWorkflow(workflowId: string, dir: string, opts: CloseWorkflowOptions): Promise<WorkflowSnapshot>;

package/dist/worktree.d.ts

@@ -1,4 +1,6 @@
 import type { GateResult } from "./core.js";
+import type { WorkflowLifecycleType } from "./workflow.js";
+export declare function gitProbeTimeoutMs(): number;
 /** One L2 parallel implement track (mstar-branch-worktree L2 table). */
 export type WorktreeTrack = {
     /** Absolute worktree checkout path for the track. */
@@ -6,13 +8,57 @@ export type WorktreeTrack = {
     /** PM-approved Working branch checked out in that worktree. */
     workingBranch: string;
 };
+/** The Git-derived main worktree of the repository containing a cwd. */
+export type MainWorktreeInfo = {
+    /** Absolute (realpath'd) main-worktree checkout root. */
+    root: string;
+    /** Branch checked out at the main worktree (`""` when detached). */
+    branch: string;
+};
+/**
+ * Discover the main worktree of the repository containing `cwd` (default
+ * `process.cwd()`): the FIRST record of `git worktree list --porcelain -z`,
+ * never the first attached branch or a name-matched path. Bounded by the
+ * shared probe timeout; unavailable Git, a hung git, a bare repository,
+ * malformed output, or an inaccessible root yield `null` — callers fail
+ * closed (`worktree.main.unresolved`), never fall through.
+ */
+export declare function readMainWorktree(cwd?: string): MainWorktreeInfo | null;
 /**
- * L1 pre-dispatch checklist input — mirrors the status.json L1 fields
- * (`metadata.control_worktree_path` + `plans[].execution_lease`).
+ * Primary-residency equality primitive: the main worktree must be on the
+ * branch RECORDED at lifecycle start (`expectedBranch` — callers transport
+ * the recorded value or the explicit `branch.base` fallback, never the
+ * branch observed at check time as its own expected value). Detached main
+ * (`branch: ""`) and any mismatch are `worktree.main.residency-switched`
+ * (high). Never switch main to satisfy this check.
+ */
+export declare function assertMainWorktreeResidency(main: MainWorktreeInfo, expectedBranch: string): GateResult;
+/**
+ * L1 pre-dispatch checklist input — the three-domain topology: the
+ * Git-derived main worktree (process-SSOT holder), the governing snapshot's
+ * dedicated integration checkout, and the plan's feature worktree
+ * (`plans[].execution_lease`). Callers carry the actual snapshot type and
+ * resolve the recorded residency expectation + active lifecycle branches
+ * from the governing snapshots.
  */
 export type L1PreDispatchInput = {
-    /** `metadata.control_worktree_path` — harness coordination SSOT checkout. */
-    controlWorktreePath: string;
+    /** Governing snapshot lifecycle type — `plan` standalone or `iteration`. */
+    workflowType: WorkflowLifecycleType;
+    /**
+     * `integration_worktree_path` — the dedicated integration checkout, on
+     * `branch.integration`. A standalone plan without integration passes `""`
+     * (both fields empty); if either field is supplied, both and the full
+     * checks are required.
+     */
+    integrationWorktreePath: string;
+    /** `branch.integration` — the branch that must be checked out at the integration worktree (`""` for a standalone plan without integration). */
+    integrationBranch: string;
+    /** Git-derived main worktree (`readMainWorktree`); `null` = unresolved — a failure, never a skipped row. */
+    mainWorktree: MainWorktreeInfo | null;
+    /** Recorded main-worktree branch (plan header) or the explicit `branch.base` fallback — never the branch observed at check time. */
+    expectedMainBranch: string;
+    /** Branches owned by ANY active lifecycle (integration/plan/track) — main must not sit on any of them, even when the recorded expectation matches. */
+    lifecycleBranches: readonly string[];
     /** `execution_lease.worktree_path` — the plan's feature worktree. */
     leaseWorktreePath: string;
     /** `execution_lease.working_branch` — the plan's Working branch. */
@@ -78,9 +124,13 @@ export declare function isDistinctCheckout(controlPath: string, candidatePath: s
 export declare function probeCheckoutRoot(path: string, opts?: BranchProbeOptions): string | null;
 /**
  * L1 cross-plan pre-dispatch checklist (mstar-branch-worktree L1 table +
- * Harness path SSOT hard rules): control path recorded, feature worktree
- * exists, lease worktree ≠ control path, and the branch checked out at the
- * feature worktree matches `execution_lease.working_branch`.
+ * iteration spec worktree-write-model § "Locked interfaces (P1 engine)"):
+ * main residency against the recorded expectation + non-ownership of any
+ * active lifecycle branch, integration presence/alignment (iterations
+ * require both integration fields; a standalone plan without integration
+ * checks main vs feature only), pairwise main/integration/feature
+ * Git-checkout identity, and the existing feature/lease checks. Null main
+ * discovery is a failure (`worktree.main.unresolved`), never a skipped row.
  */
 export declare function l1PreDispatchCheck(input: L1PreDispatchInput, opts?: BranchProbeOptions): GateResult;
 /**
@@ -94,14 +144,14 @@ export declare function l1PreDispatchCheck(input: L1PreDispatchInput, opts?: Bra
  */
 export declare function l2PreDispatchCheck(input: L2PreDispatchInput, opts?: BranchProbeOptions): GateResult;
 /**
- * L1 hard rule (Harness path SSOT): `execution_lease.worktree_path` MUST
- * be a Git checkout DISTINCT from `metadata.control_worktree_path` — the
- * same checkout, a plain subdirectory, or a symlink alias of the control
- * checkout is refused (checkout identity via the canonical per-worktree
- * git dir; probe failure fails closed). Both-empty stays a match (nothing
- * recorded, per the lease validator contract); one empty has nothing to
- * compare and passes (the lease validator's absolute-path requirement owns
- * empty lease paths).
+ * L1 hard rule (main control root vs feature): `execution_lease.worktree_path`
+ * MUST be a Git checkout DISTINCT from the MAIN worktree (the process-SSOT
+ * control root) — the same checkout, a plain subdirectory, or a symlink
+ * alias of the main checkout is refused (checkout identity via the
+ * canonical per-worktree git dir; probe failure fails closed). Both-empty
+ * stays a match (nothing recorded, per the lease validator contract); one
+ * empty has nothing to compare and passes (the lease validator's
+ * absolute-path requirement owns empty lease paths).
  */
 export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string, opts?: BranchProbeOptions): GateResult;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.8.3",
+  "version": "3.9.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {