snipara-companion 1.3.1 → 1.3.2

package/README.md

@@ -112,6 +112,14 @@ The mental model is intentionally close to Git:
 | `git format-patch` | `snipara-companion handoff`               |
 | `git checkout`     | `snipara-companion workflow resume`       |
 
+`snipara-companion final-commit` closes the local workflow and asks the hosted
+API only for the final Team Sync handoff. The CLI sends a compact summary with a
+longer timeout, retries once with a shorter summary on transient hosted failures,
+and then records a local fallback handoff in `.snipara/team-sync/session.json`
+if the hosted call still times out. A hosted final-commit timeout does not modify
+Git state. Custom final-commit categories are namespaced under `final-commit`
+before the hosted call so they stay on the handoff-only path.
+
 ## Verification Plans
 
 Use `verify` when an agent asks what to prove before handoff or release:

package/dist/index.d.ts

@@ -949,6 +949,8 @@ declare class RLMClient {
         category?: string;
         outcome?: "completed" | "partial" | "blocked" | "abandoned";
         filesTouched?: string[];
+        persistTypes?: string[];
+        handoffOnly?: boolean;
     }): Promise<Record<string, unknown>>;
     journalAppend(text: string, tags?: string[]): Promise<JournalAppendResult>;
 }

package/dist/index.js

@@ -1304,7 +1304,8 @@ var RLMClient = class {
       category: args.category,
       outcome: args.outcome || "completed",
       files_touched: args.filesTouched || [],
-      persist_types: ["decision", "learning", "workflow"]
+      persist_types: args.persistTypes ?? ["decision", "learning", "workflow"],
+      ...args.handoffOnly !== void 0 ? { handoff_only: args.handoffOnly } : {}
     });
   }
   async journalAppend(text, tags) {
@@ -8234,6 +8235,11 @@ var import_chalk5 = __toESM(require("chalk"));
 var DEFAULT_SESSION_CONTEXT_TOKENS = 1e3;
 var DEFAULT_FULL_WORKFLOW_CRITICAL_TOKENS = 2e3;
 var DEFAULT_SHARED_CONTEXT_TOKENS = 2e3;
+var TASK_COMMIT_TIMEOUT_MS = 3e4;
+var FINAL_COMMIT_TIMEOUT_MS = 9e4;
+var FINAL_COMMIT_RETRY_TIMEOUT_MS = 45e3;
+var FINAL_COMMIT_SUMMARY_MAX_CHARS = 1200;
+var FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS = 600;
 var SHARED_CONTEXT_INTENT_PATTERN = /\b(standard|standards|convention|conventions|guideline|guidelines|best practice|best practices|policy|policies|compliance|compliant|security rules|team rules|style guide|playbook|checklist)\b/i;
 var DOCUMENT_SYNC_FORMATS = {
   ".adoc": { kind: "DOC", format: "adoc" },
@@ -8469,6 +8475,52 @@ function toPreview(value, maxLength = 160) {
   }
   return "n/a";
 }
+function positiveIntegerEnv(name, fallback) {
+  const value = process.env[name];
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function compactWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function truncateText(value, maxLength) {
+  const normalized = compactWhitespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  const suffix = " ... [truncated locally for hosted final-commit]";
+  return `${normalized.slice(0, Math.max(0, maxLength - suffix.length)).trimEnd()}${suffix}`;
+}
+function buildHostedFinalCommitSummary(args) {
+  const prefix = args.workflowId ? `Workflow ${args.workflowId}
+Final commit
+` : "";
+  const budget = Math.max(80, args.maxLength - prefix.length);
+  return `${prefix}${truncateText(args.summary, budget)}`;
+}
+function hostedCommitErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function shouldRetryHostedFinalCommit(error) {
+  const message = hostedCommitErrorMessage(error).toLowerCase();
+  if (error instanceof Error && error.name === "AbortError") {
+    return true;
+  }
+  return /abort|timeout|timed out|network|fetch|econn|etimedout|http 5\d\d/.test(message);
+}
+function isFinalCommitCategory(category) {
+  return Boolean(category?.toLowerCase().includes("final-commit"));
+}
+function normalizeFinalCommitCategory(category) {
+  const normalized = compactWhitespace(category ?? "");
+  if (!normalized) {
+    return "final-commit";
+  }
+  return isFinalCommitCategory(normalized) ? normalized : `final-commit:${normalized}`;
+}
 function getPlanStepDisplayTitle(step, index = 0) {
   if (typeof step === "string") {
     return toPreview(step);
@@ -12185,7 +12237,7 @@ function printWorkflowTeamSyncResume(result) {
 }
 async function commitTaskMemory(options) {
   ensureConfigured();
-  const client = createClient(3e4);
+  const client = createClient(TASK_COMMIT_TIMEOUT_MS);
   return client.endOfTaskCommit({
     summary: options.summary,
     category: options.category,
@@ -12193,6 +12245,101 @@ async function commitTaskMemory(options) {
     filesTouched: options.files
   });
 }
+function recordLocalFinalCommitHandoff(options) {
+  const rootDir = process.cwd();
+  autoArchiveTeamSyncState(rootDir);
+  const state = loadTeamSyncState(rootDir);
+  const record = buildTeamSyncHandoffRecord({
+    summary: truncateText(options.summary, FINAL_COMMIT_SUMMARY_MAX_CHARS),
+    files: options.files,
+    attention: options.outcome === "completed" ? "watch" : "proof",
+    next: options.outcome === "completed" ? "Review this local fallback handoff before starting follow-up work." : "Resolve the blocker captured in this local fallback handoff."
+  });
+  state.handoffs.push(record);
+  state.updatedAt = record.createdAt;
+  saveTeamSyncState(state, rootDir);
+  return {
+    status: "local_fallback",
+    record_id: record.id,
+    state_path: getTeamSyncStatePath(rootDir),
+    category: "team_sync_handoff",
+    source_session_id: "local-companion-fallback",
+    files: record.files,
+    error: options.error
+  };
+}
+async function commitFinalTaskMemory(options) {
+  ensureConfigured();
+  const category = normalizeFinalCommitCategory(options.category);
+  const attempts = [];
+  const primarySummary = buildHostedFinalCommitSummary({
+    workflowId: options.workflowId,
+    summary: options.summary,
+    maxLength: FINAL_COMMIT_SUMMARY_MAX_CHARS
+  });
+  const retrySummary = buildHostedFinalCommitSummary({
+    workflowId: options.workflowId,
+    summary: options.summary,
+    maxLength: FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS
+  });
+  const callHosted = async (summary, timeoutMs) => {
+    const client = createClient(timeoutMs);
+    const handoffOnly = isFinalCommitCategory(category);
+    return client.endOfTaskCommit({
+      summary,
+      category,
+      outcome: options.outcome,
+      filesTouched: options.files,
+      persistTypes: handoffOnly ? [] : ["decision", "learning", "workflow"],
+      handoffOnly
+    });
+  };
+  try {
+    return await callHosted(
+      primarySummary,
+      positiveIntegerEnv("SNIPARA_FINAL_COMMIT_TIMEOUT_MS", FINAL_COMMIT_TIMEOUT_MS)
+    );
+  } catch (error) {
+    attempts.push({
+      summary_chars: primarySummary.length,
+      error: hostedCommitErrorMessage(error)
+    });
+    if (shouldRetryHostedFinalCommit(error)) {
+      try {
+        return await callHosted(
+          retrySummary,
+          positiveIntegerEnv("SNIPARA_FINAL_COMMIT_RETRY_TIMEOUT_MS", FINAL_COMMIT_RETRY_TIMEOUT_MS)
+        );
+      } catch (retryError) {
+        attempts.push({
+          summary_chars: retrySummary.length,
+          error: hostedCommitErrorMessage(retryError)
+        });
+      }
+    }
+  }
+  const lastError = attempts[attempts.length - 1]?.error ?? "hosted final-commit failed";
+  const localHandoff = recordLocalFinalCommitHandoff({
+    summary: options.summary,
+    outcome: options.outcome,
+    files: options.files,
+    error: lastError
+  });
+  return {
+    stored_count: 0,
+    skipped_count: 0,
+    candidates: [],
+    stored_candidates: [],
+    skipped_candidates: [],
+    team_sync_handoff: localHandoff,
+    hosted_final_commit: {
+      status: "error",
+      attempts,
+      message: "Hosted snipara_end_of_task_commit failed; local workflow state and Team Sync fallback handoff were preserved."
+    },
+    message: "Hosted final-commit failed; local fallback handoff created"
+  };
+}
 function printJournalWarning(result) {
   if (result?.status === "error" && result.error) {
     console.log(`Journal checkpoint: ${result.error}`);
@@ -12266,10 +12413,11 @@ async function finalCommitCommand(options) {
   });
   const state = readWorkflowState2();
   const outcome = options.outcome ?? "completed";
-  const summary = state ? [`Workflow ${state.workflowId}`, "Final commit", options.summary].join("\n") : options.summary;
-  const result = await commitTaskMemory({
-    summary,
-    category: options.category ?? "final-commit",
+  const category = normalizeFinalCommitCategory(options.category);
+  const result = await commitFinalTaskMemory({
+    workflowId: state?.workflowId,
+    summary: options.summary,
+    category,
     outcome,
     files: options.files
   });
@@ -12279,7 +12427,7 @@ async function finalCommitCommand(options) {
     state.currentPhaseId = outcome === "completed" ? void 0 : state.currentPhaseId;
     state.updatedAt = now;
     state.lastCommit = {
-      category: options.category ?? "final-commit",
+      category,
       outcome,
       summary: options.summary,
       committedAt: now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Snipara Git-style companion CLI for hosted context, agent continuity, hooks, and automation workflows",
   "main": "dist/index.js",
   "bin": {