@mstar-harness/engine 3.11.0 → 3.11.1

package/dist/coordination-write.d.ts

@@ -1,6 +1,6 @@
 import type { ValidationResult } from "./core.js";
 /** Stable refusal codes of the scoped coordination surface (spec §C4). */
-export declare const COORDINATION_ERROR_CODES: readonly ["coordination.harness-not-found", "coordination.workflow-not-found", "coordination.plan-not-found", "coordination.scope-mismatch", "coordination.path-mismatch", "coordination.assignment-invalid", "coordination.assignment-stale", "coordination.not-prepared", "coordination.duplicate-holder", "coordination.session-mismatch", "coordination.session-not-found", "coordination.session-role", "coordination.version-conflict", "coordination.expected-version-required", "coordination.invalid-transition", "coordination.invalid-input", "coordination.forbidden-field", "coordination.not-in-git", "coordination.git-unavailable", "coordination.git-proof", "coordination.evidence-stale", "coordination.integration-unresolved", "coordination.integration-diverged", "coordination.local-store-required", "coordination.direct-write-refused", "coordination.scoped-writer-required", "coordination.unknown-operation", "coordination.store", "coordination.prepare-amendment.stale", "coordination.prepare-amendment.invalid-patch", "coordination.prepare-amendment.not-prepare", "coordination.prepare-amendment.execution-started", "coordination.prepare-amendment.duplicate-plan", "coordination.prepare-amendment.invalid-plan", "coordination.prepare-amendment.compass-mismatch", "coordination.prepare-amendment.invalid-worktree", "coordination.delivery-source-repair.unsupported-workflow", "coordination.delivery-source-repair.terminal", "coordination.delivery-source-repair.no-accepted-handoff", "coordination.delivery-source-repair.already-aligned", "coordination.delivery-source-repair.not-legacy-shape", "coordination.delivery-source-repair.pr-conflict"];
+export declare const COORDINATION_ERROR_CODES: readonly ["coordination.harness-not-found", "coordination.workflow-not-found", "coordination.plan-not-found", "coordination.scope-mismatch", "coordination.path-mismatch", "coordination.assignment-invalid", "coordination.assignment-stale", "coordination.not-prepared", "coordination.duplicate-holder", "coordination.session-mismatch", "coordination.session-not-found", "coordination.session-role", "coordination.invalid-session-id", "coordination.version-conflict", "coordination.expected-version-required", "coordination.invalid-transition", "coordination.invalid-input", "coordination.forbidden-field", "coordination.not-in-git", "coordination.git-unavailable", "coordination.git-proof", "coordination.evidence-stale", "coordination.integration-unresolved", "coordination.integration-diverged", "coordination.local-store-required", "coordination.direct-write-refused", "coordination.scoped-writer-required", "coordination.unknown-operation", "coordination.store", "coordination.prepare-amendment.stale", "coordination.prepare-amendment.invalid-patch", "coordination.prepare-amendment.not-prepare", "coordination.prepare-amendment.execution-started", "coordination.prepare-amendment.duplicate-plan", "coordination.prepare-amendment.invalid-plan", "coordination.prepare-amendment.compass-mismatch", "coordination.prepare-amendment.invalid-worktree", "coordination.delivery-source-repair.unsupported-workflow", "coordination.delivery-source-repair.terminal", "coordination.delivery-source-repair.no-accepted-handoff", "coordination.delivery-source-repair.already-aligned", "coordination.delivery-source-repair.not-legacy-shape", "coordination.delivery-source-repair.pr-conflict"];
 export type CoordinationErrorCode = (typeof COORDINATION_ERROR_CODES)[number];
 /**
  * Stable exception of the coordination surface: `code` is the consumer

package/dist/coordination.d.ts

@@ -38,7 +38,7 @@ export type ResolvedPlanScope = {
 };
 /**
  * Session envelope persisted at
- * `{WORKFLOW_DIR}/<workflow-id>/sessions/<session-id>.json` (mode `0600`).
+ * `{WORKFLOW_DIR}/<workflow-id>/sessions/<role>-<session-id>.json` (mode `0600`).
  * The envelope is the durable proof of who holds the session: the snapshot
  * stores its canonical path and every later call must present the same file.
  */
@@ -51,20 +51,24 @@ export type CoordinationSession = {
     harness_root: string;
 };
 /**
- * Bind addressing (spec §B). A fresh bind never supplies a session path: the
- * engine generates the session UUID and creates
- * `<workflow-dir>/<workflow-id>/sessions/<session-id>.json` itself. An existing
- * session is reached only through its explicit `resumePath`, which resumes
- * read-only and never writes.
+ * Bind addressing (spec §B). A fresh bind generates the session UUID and
+ * creates `<workflow-dir>/<workflow-id>/sessions/<role>-<session-id>.json`
+ * itself, unless the caller supplies `sessionId` — then the engine adopts that
+ * value as the identity after validating it as a single safe path component (it
+ * names the envelope's file, prefixed by the role). An existing session is
+ * reached only through its explicit `resumePath`, which resumes read-only,
+ * never writes and never re-identifies.
  */
 export type BindPlanSessionInput = {
     scope: PlanScopeInput;
     cwd: string;
+    sessionId?: string;
 } | {
     coordinator: true;
     workflowId: string;
     harnessDir?: string;
     cwd: string;
+    sessionId?: string;
 } | {
     resumePath: string;
     cwd: string;
@@ -263,8 +267,10 @@ export declare function readCoordinatedArtifact(harnessRoot: string, ref: Artifa
  */
 /**
  * Bind a session (spec §B, §C2). Fresh addressing never supplies a session
- * path: the engine generates the UUID and creates the envelope. `resumePath`
- * names an existing envelope and resumes read-only.
+ * path: the engine generates the UUID — or adopts the caller-supplied
+ * `sessionId`, refused unless it is a single safe path component — and creates
+ * the envelope. `resumePath` names an existing envelope and resumes read-only,
+ * so it takes no identity input at all.
  */
 export declare function bindPlanSession(input: BindPlanSessionInput): Promise<CoordinationResult>;
 /**

package/dist/engine.js

@@ -10376,8 +10376,8 @@ function reportedBranchesOf(row) {
 function snapshotPathOf(harnessRoot, workflowId) {
   return join20(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), workflowId, SNAPSHOT_FILE2);
 }
-function sessionFilePath(harnessRoot, workflowId, sessionId) {
-  return join20(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), workflowId, SESSION_DIR, `${sessionId}.json`);
+function sessionFilePath(harnessRoot, workflowId, role, sessionId) {
+  return join20(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), workflowId, SESSION_DIR, `${role}-${sessionId}.json`);
 }
 function localStore(harnessRoot) {
   let store;
@@ -10538,6 +10538,22 @@ function safePlanId(planId, where) {
   }
   return planId;
 }
+var SESSION_ID_MAX_LENGTH = 128;
+function safeSessionId(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string")
+    throw invalidInput("sessionId must be a string");
+  if (value.length > SESSION_ID_MAX_LENGTH) {
+    throw new CoordinationError("coordination.invalid-session-id", `session id is longer than ${SESSION_ID_MAX_LENGTH} characters: ${JSON.stringify(value)}`, { session_id: value, max_length: SESSION_ID_MAX_LENGTH });
+  }
+  try {
+    assertSafePathComponent(value, "session id");
+  } catch (error) {
+    throw new CoordinationError("coordination.invalid-session-id", `session id ${JSON.stringify(value)} is not a safe path component: ${errorMessage(error)}`, { session_id: value });
+  }
+  return value;
+}
 function readSnapshot(dir) {
   const snapshotPath = join20(dir, SNAPSHOT_FILE2);
   if (!existsSync15(snapshotPath)) {
@@ -10721,7 +10737,7 @@ function readSessionEnvelope(sessionPath) {
   return session;
 }
 function createSessionEnvelope(session) {
-  const path = sessionFilePath(session.harness_root, session.workflow_id, session.session_id);
+  const path = sessionFilePath(session.harness_root, session.workflow_id, session.role, session.session_id);
   mkdirSync9(dirname12(path), { recursive: true });
   try {
     writeFileSync7(path, `${JSON.stringify(session, null, 2)}
@@ -11026,7 +11042,7 @@ function assertCoordinatorResidency(cwd, snapshot) {
   }
   return main;
 }
-async function bindCoordinatorSession(cwd, workflowId, harnessDir) {
+async function bindCoordinatorSession(cwd, workflowId, harnessDir, sessionId) {
   const harnessRoot = requireProcessRoot(cwd, harnessDir);
   safePlanId(workflowId, "workflowId");
   const snapshotPath = snapshotPathOf(harnessRoot, workflowId);
@@ -11035,7 +11051,7 @@ async function bindCoordinatorSession(cwd, workflowId, harnessDir) {
   const session = {
     schema_version: 1,
     role: "coordinator",
-    session_id: randomUUID2(),
+    session_id: sessionId ?? randomUUID2(),
     workflow_id: workflowId,
     harness_root: harnessRoot
   };
@@ -11075,7 +11091,7 @@ function requireProcessRoot(cwd, harnessDir) {
   }
   return root;
 }
-async function bindPlanSessionForPlan(scope) {
+async function bindPlanSessionForPlan(scope, sessionId) {
   const { harnessRoot, workflowId, planId } = scope;
   const snapshotPath = snapshotPathOf(harnessRoot, workflowId);
   assertSnapshotPath(harnessRoot, workflowId, snapshotPath);
@@ -11098,7 +11114,7 @@ async function bindPlanSessionForPlan(scope) {
   const session = {
     schema_version: 1,
     role: "plan-pm",
-    session_id: randomUUID2(),
+    session_id: sessionId ?? randomUUID2(),
     workflow_id: workflowId,
     plan_id: planId,
     harness_root: harnessRoot
@@ -11165,19 +11181,21 @@ async function bindPlanSession(input) {
     return resumeBoundSession(input.resumePath);
   }
   if ("coordinator" in input) {
-    assertExactKeys(input, ["coordinator", "workflowId", "harnessDir", "cwd"], "bind coordinator input");
+    assertExactKeys(input, ["coordinator", "workflowId", "harnessDir", "cwd", "sessionId"], "bind coordinator input");
     if (input.coordinator !== true)
       throw invalidInput("`coordinator` is only meaningful as true");
     if (!isNonEmptyString(input.workflowId))
       throw invalidInput("workflowId is required");
     requireCwd(input.cwd);
-    return bindCoordinatorSession(input.cwd, input.workflowId, input.harnessDir);
+    const sessionId2 = safeSessionId(input.sessionId);
+    return bindCoordinatorSession(input.cwd, input.workflowId, input.harnessDir, sessionId2);
   }
-  assertExactKeys(input, ["scope", "cwd"], "bind plan input");
+  assertExactKeys(input, ["scope", "cwd", "sessionId"], "bind plan input");
   if (!isPlainObject2(input.scope))
     throw invalidInput("a plan bind requires a scope");
   requireCwd(input.cwd);
-  return bindPlanSessionForPlan(await resolvePlanScope(input.scope, input.cwd));
+  const sessionId = safeSessionId(input.sessionId);
+  return bindPlanSessionForPlan(await resolvePlanScope(input.scope, input.cwd), sessionId);
 }
 function requireCwd(cwd) {
   if (!isNonEmptyString(cwd) || !isAbsolute12(cwd))

package/package.json

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