snipara-companion 3.5.7 → 3.5.9

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.5.9
+
+- Routes explicit `workflow phase-commit` and `final-commit` rationale through
+  the hosted atomic `why` block instead of issuing a second Why Capture request.
+- Exposes decision, rationale, alternatives, constraints, and observed outcome
+  inputs on workflow commits while keeping candidates review-pending.
+- Preserves handoff-only final commits when no structured rationale is supplied.
+
+## New In 3.5.8
+
+- Preserves the exact collaboration actor identity on hosted lease heartbeat
+  and release requests, preventing owner-authenticated cleanup from falling
+  back to the API-key actor and returning a false `403`.
+
 ## New In 3.5.7
 
 - Bounds the best-effort hosted judgment lookup in `run` to 8 seconds instead

package/dist/index.d.ts

@@ -519,6 +519,13 @@ interface WhyCaptureResult {
         failed?: Array<Record<string, unknown>>;
     };
 }
+interface EndOfTaskCommitWhyInput {
+    decision?: string;
+    rationale?: string;
+    alternatives?: string[];
+    constraints?: string[];
+    observedOutcome?: string;
+}
 interface JournalAppendResult {
     success?: boolean;
     date?: string;
@@ -1471,7 +1478,7 @@ declare class RLMClient {
         resources?: CollaborationResource[];
         metadata?: Record<string, unknown>;
     }): Promise<CollaborationLeaseResponse>;
-    updateCollaborationLease(leaseId: string, args: {
+    updateCollaborationLease(leaseId: string, args: CollaborationActorPayload & {
         action?: "heartbeat" | "release" | "override";
         reason?: string;
     }): Promise<CollaborationLeaseUpdateResponse>;
@@ -1516,6 +1523,8 @@ declare class RLMClient {
     getSessionMemories(maxCriticalTokens?: number, maxDailyTokens?: number, includeYesterday?: boolean): Promise<SessionMemoriesResult>;
     endOfTaskCommit(args: {
         summary: string;
+        task?: string;
+        why?: EndOfTaskCommitWhyInput;
         category?: string;
         outcome?: "completed" | "partial" | "blocked" | "abandoned";
         filesTouched?: string[];

package/dist/index.js

@@ -1724,6 +1724,16 @@ var RLMClient = class {
   async endOfTaskCommit(args) {
     return this.mcpCall("snipara_end_of_task_commit", {
       summary: args.summary,
+      ...args.task ? { task: args.task } : {},
+      ...args.why ? {
+        why: {
+          ...args.why.decision ? { decision: args.why.decision } : {},
+          ...args.why.rationale ? { rationale: args.why.rationale } : {},
+          ...args.why.alternatives ? { alternatives: args.why.alternatives } : {},
+          ...args.why.constraints ? { constraints: args.why.constraints } : {},
+          ...args.why.observedOutcome ? { observed_outcome: args.why.observedOutcome } : {}
+        }
+      } : {},
       category: args.category,
       outcome: args.outcome || "completed",
       files_touched: args.filesTouched || [],
@@ -12285,6 +12295,79 @@ function uniqueStrings12(values) {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
 
+// ../project-intelligence-contracts/src/why-capture-confidence-v1.json
+var why_capture_confidence_v1_default = {
+  version: "why-capture-confidence-v1",
+  base: 0.72,
+  decisionRationaleBonus: 0.1,
+  nonManualSourceBonus: 0.04,
+  maximum: 0.9,
+  decimalPlaces: 2,
+  validatedExecutionOutcomes: ["completed"],
+  vectors: [
+    {
+      candidateType: "CONTEXT",
+      hasDecision: false,
+      hasRationale: false,
+      sourceKind: "manual",
+      executionOutcome: "completed",
+      expected: 0.72
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "manual",
+      executionOutcome: "completed",
+      expected: 0.82
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "completed",
+      expected: 0.86
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "partial",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "blocked",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "abandoned",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: false,
+      sourceKind: "final_commit",
+      executionOutcome: "completed",
+      expected: 0.76
+    }
+  ]
+};
+
+// ../project-intelligence-contracts/src/why-capture-confidence.ts
+var WHY_CAPTURE_CONFIDENCE_VERSION = why_capture_confidence_v1_default.version;
+var WHY_CAPTURE_CONFIDENCE_TEST_VECTORS = why_capture_confidence_v1_default.vectors;
+
 // src/commands/decision-requests.ts
 var fs12 = __toESM(require("fs"));
 var path11 = __toESM(require("path"));
@@ -16659,7 +16742,12 @@ async function heartbeatHostedLeases(context, leaseIds) {
   }
   try {
     const data = await Promise.all(
-      leaseIds.map((leaseId) => client.updateCollaborationLease(leaseId, { action: "heartbeat" }))
+      leaseIds.map(
+        (leaseId) => client.updateCollaborationLease(leaseId, {
+          ...context.actor,
+          action: "heartbeat"
+        })
+      )
     );
     return { status: "ok", data };
   } catch (error) {
@@ -16675,6 +16763,7 @@ async function releaseHostedLeases(context, leaseIds, input) {
     const data = await Promise.all(
       leaseIds.map(
         (leaseId) => client.updateCollaborationLease(leaseId, {
+          ...context.actor,
           action: "release",
           reason: input.reason
         })
@@ -17822,16 +17911,16 @@ function previewCandidateReceipt(value) {
   if (!isRecord9(value)) {
     return void 0;
   }
-  const whyFields = isRecord9(value.whyFields) ? value.whyFields : void 0;
+  const whyFields = isRecord9(value.whyFields) ? value.whyFields : isRecord9(value.why_fields) ? value.why_fields : void 0;
   const decision = boundedText(whyFields?.decision);
-  const rationale = boundedText(whyFields?.why);
-  const text = boundedText(value.content) ?? decision;
+  const rationale = boundedText(whyFields?.why ?? whyFields?.rationale);
+  const text = boundedText(value.content ?? value.text) ?? decision;
   if (!text) {
     return void 0;
   }
   return {
     text,
-    ...boundedText(value.type, 80) ? { type: boundedText(value.type, 80) } : {},
+    ...boundedText(value.type ?? value.memory_type, 80) ? { type: boundedText(value.type ?? value.memory_type, 80) } : {},
     ...boundedText(value.category, 120) ? { category: boundedText(value.category, 120) } : {},
     ...decision ? { decision } : {},
     ...rationale ? { rationale } : {}
@@ -17842,23 +17931,25 @@ function pendingMemoryReceipt(value) {
     return void 0;
   }
   const memoryId = boundedText(value.memory_id ?? value.memoryId ?? value.id, 200);
-  const text = boundedText(value.content) ?? (memoryId ? `Memory ${memoryId}` : void 0);
+  const text = boundedText(value.content ?? value.text) ?? (memoryId ? `Memory ${memoryId}` : void 0);
   if (!text) {
     return void 0;
   }
   return {
     ...memoryId ? { memoryId } : {},
     text,
-    ...boundedText(value.type, 80) ? { type: boundedText(value.type, 80) } : {},
-    ...boundedText(value.category, 120) ? { category: boundedText(value.category, 120) } : {},
-    reviewStatus: boundedText(value.review_status ?? value.reviewStatus, 80) ?? "pending"
+    ...boundedText(value.type ?? value.memory_type, 80) ? { type: boundedText(value.type ?? value.memory_type, 80) } : {},
+    category: boundedText(value.category, 120) ?? "why-capture",
+    reviewStatus: boundedText(value.review_status ?? value.reviewStatus, 80) ?? "PENDING"
   };
 }
 function issueReceipt(value, fallbackReason) {
   if (!isRecord9(value)) {
     return void 0;
   }
-  const text = boundedText(value.content ?? value.decision ?? value.title ?? value.error ?? value.reason) ?? "Why Capture item";
+  const text = boundedText(
+    value.content ?? value.decision ?? value.title ?? value.error ?? value.reason ?? value.decision_id ?? value.id
+  ) ?? "Why Capture item";
   const reason = boundedText(value.reason ?? value.error, 160) ?? fallbackReason;
   return { text, ...reason ? { reason } : {} };
 }
@@ -17896,6 +17987,47 @@ function readLatestWorkflowCommands(cwd) {
   }
   return [];
 }
+function recordItems(value) {
+  return Array.isArray(value) ? value.filter(isRecord9) : [];
+}
+function taskCommitWhyCaptureReceipt(result, sourceKind, cwd = process.cwd()) {
+  const commitSha = readCommitSha(cwd);
+  const candidates = recordItems(result.candidates).filter(
+    (candidate) => isRecord9(candidate.why_fields) || isRecord9(candidate.whyFields)
+  );
+  const storedCandidates = recordItems(result.stored_candidates).filter(
+    (candidate) => isRecord9(candidate.why_fields) || isRecord9(candidate.whyFields)
+  );
+  const decisionCapture = isRecord9(result.decision_capture) ? result.decision_capture : {};
+  const duplicates = recordItems(decisionCapture.duplicates).map((item) => issueReceipt(item, "duplicate")).filter((item) => Boolean(item));
+  const failed = recordItems(decisionCapture.failed).map((item) => issueReceipt(item, "capture_failed")).filter((item) => Boolean(item));
+  const caveats = Array.isArray(result.caveats) ? result.caveats.filter((item) => typeof item === "string") : [];
+  const hostedPhaseCommit = isRecord9(result.hosted_phase_commit) ? result.hosted_phase_commit : void 0;
+  const hostedFinalCommit = isRecord9(result.hosted_final_commit) ? result.hosted_final_commit : void 0;
+  const hostedError = boundedText(hostedPhaseCommit?.error ?? hostedFinalCommit?.error);
+  const previewCandidates = candidates.map(previewCandidateReceipt).filter((item) => Boolean(item));
+  const pendingMemories = storedCandidates.map(pendingMemoryReceipt).filter((item) => Boolean(item));
+  const baseReceipt = {
+    sourceKind,
+    previewCandidateCount: previewCandidates.length,
+    capturedCount: pendingMemories.length,
+    previewCandidates,
+    pendingMemories,
+    duplicates,
+    failed,
+    ...commitSha ? { commitSha } : {}
+  };
+  if (hostedError) {
+    return { ...baseReceipt, status: "error", error: hostedError };
+  }
+  if (caveats.includes("why_requires_human_owner")) {
+    return { ...baseReceipt, status: "skipped", error: "why_requires_human_owner" };
+  }
+  if (candidates.length === 0) {
+    return { ...baseReceipt, status: "no_candidates" };
+  }
+  return { ...baseReceipt, status: "captured" };
+}
 async function captureCompanionWhy(input) {
   const cwd = input.cwd ?? process.cwd();
   const commitSha = readCommitSha(cwd);
@@ -20660,7 +20792,7 @@ function recordList(value) {
   return Array.isArray(value) ? value.filter(isRecord11) : [];
 }
 function buildWorkflowPhaseCommitReceipt(input) {
-  const stored = recordList(input.result.stored_candidates).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
+  const stored = recordList(input.result.stored_candidates).filter((item) => !isRecord11(item.why_fields) && !isRecord11(item.whyFields)).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
   const skipped = recordList(input.result.skipped_candidates).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
   const hostedPhaseCommit = isRecord11(input.result.hosted_phase_commit) ? input.result.hosted_phase_commit : void 0;
   return {
@@ -32147,6 +32279,8 @@ async function commitTaskMemory(options) {
   const client = createClient(TASK_COMMIT_TIMEOUT_MS);
   return client.endOfTaskCommit({
     summary: options.summary,
+    task: options.task,
+    why: options.why,
     category: options.category,
     outcome: options.outcome,
     filesTouched: options.files
@@ -32219,9 +32353,11 @@ async function commitFinalTaskMemory(options) {
   });
   const callHosted = async (summary, timeoutMs) => {
     const client = createClient(timeoutMs);
-    const handoffOnly = isFinalCommitCategory(category);
+    const handoffOnly = isFinalCommitCategory(category) && !options.why;
     return client.endOfTaskCommit({
       summary,
+      task: options.task,
+      why: options.why,
       category,
       outcome: options.outcome,
       filesTouched: options.files,
@@ -32275,6 +32411,28 @@ async function commitFinalTaskMemory(options) {
     message: "Hosted final-commit failed; local fallback handoff created"
   };
 }
+function structuredTaskCommitWhy(options) {
+  const rationale = compactWhitespace2(options.why ?? "");
+  const explicitDecision = compactWhitespace2(options.decision ?? "");
+  const alternatives = [
+    ...new Set((options.alternatives ?? []).map(compactWhitespace2).filter(Boolean))
+  ];
+  const constraints = [
+    ...new Set((options.constraints ?? []).map(compactWhitespace2).filter(Boolean))
+  ];
+  const observedOutcome = compactWhitespace2(options.observedOutcome ?? "");
+  const decision = explicitDecision || (rationale ? compactWhitespace2(options.summary) : "");
+  if (!decision && !rationale && alternatives.length === 0 && constraints.length === 0 && !observedOutcome) {
+    return void 0;
+  }
+  return {
+    ...decision ? { decision } : {},
+    ...rationale ? { rationale } : {},
+    ...alternatives.length > 0 ? { alternatives } : {},
+    ...constraints.length > 0 ? { constraints } : {},
+    ...observedOutcome ? { observedOutcome } : {}
+  };
+}
 function printJournalWarning(result) {
   if (result?.status === "error" && result.error) {
     console.log(`Journal checkpoint: ${result.error}`);
@@ -32320,8 +32478,11 @@ async function workflowPhaseCommitCommand(options) {
     phase,
     summary: options.summary
   });
+  const structuredWhy = structuredTaskCommitWhy(options);
   const result = await commitPhaseTaskMemory({
     summary: durableSummary,
+    task: `${state.goal} / ${phase.title}`,
+    why: structuredWhy,
     category,
     outcome,
     files
@@ -32396,14 +32557,7 @@ async function workflowPhaseCommitCommand(options) {
     journalAttempted: true,
     teamSyncCompletionAttempted: shouldCompleteTeamSyncWork
   });
-  const whyCapture = await captureCompanionWhy({
-    sourceKind: "phase_commit",
-    sourceSessionId: state.workflowId,
-    task: `${state.goal} / ${phase.title}`,
-    summary: options.summary,
-    files,
-    commands: readLatestWorkflowCommands(process.cwd())
-  });
+  const whyCapture = taskCommitWhyCaptureReceipt(result, "phase_commit");
   phaseCommitReceipt.whyCapture = whyCapture;
   writeWorkflowState(state);
   const coordinationRelease = await releaseWorkflowCoordination(
@@ -32501,8 +32655,11 @@ async function finalCommitCommand(options) {
   });
   const outcome = options.outcome ?? "completed";
   const category = normalizeFinalCommitCategory(options.category);
+  const structuredWhy = structuredTaskCommitWhy(options);
   const result = await commitFinalTaskMemory({
     workflowId: state?.workflowId,
+    task: state?.goal,
+    why: structuredWhy,
     summary: options.summary,
     category,
     outcome,
@@ -32554,15 +32711,7 @@ async function finalCommitCommand(options) {
     journalAttempted: true,
     teamSyncCompletionAttempted: outcome === "completed"
   });
-  const whyCapture = await captureCompanionWhy({
-    sourceKind: "final_commit",
-    sourceSessionId: state?.workflowId ?? loadConfig().sessionId,
-    task: state?.goal,
-    summary: options.summary,
-    why: options.why,
-    files: options.files,
-    commands: readLatestWorkflowCommands(process.cwd())
-  });
+  const whyCapture = taskCommitWhyCaptureReceipt(result, "final_commit");
   const coordinationRelease = state ? await releaseWorkflowCoordination(state, `Workflow ${state.workflowId} final-commit.`) : void 0;
   const report = buildFinalCommitReport({
     state,
@@ -39955,7 +40104,7 @@ workflow.command("runtime-checkpoint").description(
 });
 workflow.command("phase-commit").description(
   "Persist a phase outcome through snipara_end_of_task_commit and advance the workflow"
-).argument("<phaseId>", "Workflow phase id").requiredOption("-s, --summary <summary>", "Phase outcome summary").option("-c, --category <category>", "Memory category", "workflow-phase").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
+).argument("<phaseId>", "Workflow phase id").requiredOption("-s, --summary <summary>", "Phase outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Memory category", "workflow-phase").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Phase evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -39964,6 +40113,11 @@ workflow.command("phase-commit").description(
   await workflowPhaseCommitCommand({
     phaseId,
     summary: options.summary,
+    decision: options.decision,
+    why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,
@@ -39971,7 +40125,7 @@ workflow.command("phase-commit").description(
     json: options.json
   });
 });
-workflow.command("final-commit").description("Persist the final workflow outcome and close the local workflow state").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--why <why>", "Decision rationale; never inferred when absent").option("-c, --category <category>", "Memory category", "final-commit").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
+workflow.command("final-commit").description("Persist the final workflow outcome and close the local workflow state").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Memory category", "final-commit").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Verification evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -39979,7 +40133,11 @@ workflow.command("final-commit").description("Persist the final workflow outcome
 ).option("--risk <risk>", "Known residual risk; repeatable", collectOption, []).option("--next-step <nextStep>", "Recommended next action").option("--json", "Print raw JSON").action(async (options) => {
   await finalCommitCommand({
     summary: options.summary,
+    decision: options.decision,
     why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,
@@ -41004,7 +41162,7 @@ program.command("task-commit").description("Persist durable outcomes after meani
     json: options.json
   });
 });
-program.command("final-commit").description("Persist the final managed workflow outcome through snipara_end_of_task_commit").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--why <why>", "Decision rationale; never inferred when absent").option("-c, --category <category>", "Category", "final-commit").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option(
+program.command("final-commit").description("Persist the final managed workflow outcome through snipara_end_of_task_commit").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Category", "final-commit").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Verification evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -41012,7 +41170,11 @@ program.command("final-commit").description("Persist the final managed workflow
 ).option("--risk <risk>", "Known residual risk; repeatable", collectOption, []).option("--next-step <nextStep>", "Recommended next action").option("--json", "Print raw JSON").action(async (options) => {
   await finalCommitCommand({
     summary: options.summary,
+    decision: options.decision,
     why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,

package/docs/FULL_REFERENCE.md

@@ -1632,10 +1632,17 @@ Companion separates two concepts:
   `workflow phase-commit` and `final-commit` keep local workflow state moving on transient
   hosted commit timeouts and surface that local fallback explicitly in the result.
 
-`final-commit` itself remains handoff-only. Its seven-section report reads the
-durable phase receipts already stored, marks Why Capture candidates as pending
-review, lists skipped/duplicate/failed items as not persisted, and never treats
-the final summary or handoff as newly approved durable memory.
+`final-commit` remains handoff-only when no structured rationale is supplied.
+When `--why` or another structured Why Capture field is present, Companion sends
+one atomic `why` block with the handoff commit; it does not issue a second capture
+request. `--decision` overrides the decision text, while `--why` uses the commit
+summary as the decision fallback. Repeat `--alternative` and `--constraint` as
+needed, and use `--observed-outcome` only for an observed result rather than the
+execution status. `workflow phase-commit` exposes the same fields. The resulting
+candidate remains pending review. The seven-section final report reads durable
+phase receipts already stored, marks Why Capture candidates as pending review,
+lists skipped/duplicate/failed items as not persisted, and never treats the final
+summary or handoff as newly approved durable memory.
 
 Do not call `snipara_end_of_task_commit` mechanically for every Git commit. For risky commits,
 package releases, or retries after failures, run Memory Guard first so the agent sees relevant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.5.7",
+  "version": "3.5.9",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {