create-snipara 1.3.43 → 1.3.45

package/README.md

@@ -178,14 +178,17 @@ Existing root `AGENTS.md` and `CLAUDE.md` files are not replaced. The installer
 adds or refreshes a marked Snipara section so project-specific instructions stay
 intact.
 
-When `snipara-companion` is installed, the companion pack also includes the compaction-safe managed workflow:
+When `snipara-companion` is installed, the companion pack also includes the compaction-safe managed workflow. Keep the machine plan in JSON for stable phase ids; an optional Markdown file can remain the human-facing contract.
 
 ```bash
-snipara-companion workflow start --goal "ship auth hardening" --plan-file ./plan.md
+snipara-companion workflow start --goal "ship auth hardening" --plan-file ./plan.json
 snipara-companion workflow phase-start context
 snipara-companion workflow run --mode full --include-session-context --query "load auth context"
 snipara-companion code impact --changed-files src/auth.ts tests/auth.test.ts --diff-summary "auth hardening"
 snipara-companion workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/auth.ts
+snipara-companion workflow resume --include-session-context
+snipara-companion workflow phase-start implementation
+snipara-companion workflow run --mode full --include-session-context --query "implement auth hardening"
 snipara-companion final-commit --summary "Shipped auth hardening and tests" --files src/auth.ts tests/auth.test.ts
 ```
 

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "1.3.43",
+  version: "1.3.45",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -1372,9 +1372,12 @@ Agent task lifecycle:
 8. Use \`snipara_plan\` or \`snipara_decompose\` only for FULL-mode work and only
    when the hosted server exposes them.
 9. When the LLM has produced a visible multi-phase plan and \`snipara-companion\`
-   is installed, run \`snipara-companion workflow start --goal "<goal>" --plan-file <plan_file>\`, then use \`workflow phase-start\`, \`workflow phase-commit\`,
-   \`workflow resume\`, and \`final-commit\` so compaction cannot lose the next
-   phase.
+   is installed, keep the machine plan in JSON and run
+   \`snipara-companion workflow start --goal "<goal>" --plan-file <plan_json_file>\`.
+   Use \`workflow phase-start\` / \`workflow phase-commit\` per phase, and after
+   \`workflow resume\` rerun \`workflow phase-start <phase_id>\` before editing
+   again. For runtime-bound phases, capture compact rehydratable Sandbox state
+   with \`workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>\`.
 10. Use local file reads, \`rg\`, git commands, and test commands for exact edits,
     current working-tree state, and verification.
 11. Treat every \`snipara_code_*\` response as indexed context: check indexed
@@ -1415,9 +1418,9 @@ Use Snipara Hosted MCP before answering project-specific questions.
 - On paid Context plans, use \`snipara_code_symbol_card\` before editing important symbols and \`snipara_code_impact\` before risky multi-file changes or PR reviews.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact edits/current working tree; use Snipara for architecture and indexed code graph context.
-- When the plan is visible and \`snipara-companion\` is installed, use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` to keep phase state durable across compaction.
+- When the plan is visible and \`snipara-companion\` is installed, keep the machine plan in JSON, use \`snipara-companion workflow start\`, \`phase-start\`, and \`phase-commit\` per phase, and after \`workflow resume\` rerun \`workflow phase-start\` before editing again.
 - If generated hooks are enabled, \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` provide runtime Rescue Pack checks when the agent loops on failures or empty searches.
-- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
+- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps. For runtime-bound phases, capture compact rehydratable state with \`workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>\`. Then \`workflow resume\` restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
 - End substantial work with \`snipara_end_of_task_commit\` when available; for managed workflows, end every phase with \`snipara-companion workflow phase-commit\` and the task with \`snipara-companion final-commit\`.
 - Use \`snipara_remember_if_novel\` or \`snipara_remember\` only for narrow durable memories.
 - Do not store secrets, one-off command output, raw logs, or unreviewed guesses in memory.
@@ -1446,9 +1449,9 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - Use \`snipara_plan\` or \`snipara_decompose\` only for complex work and only when available.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
-- When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` so the next phase survives compaction.
+- When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, keep the machine plan in JSON, use \`snipara-companion workflow start\`, \`phase-start\`, and \`phase-commit\` per phase, and after \`workflow resume\` rerun \`workflow phase-start\` before editing again.
 - Generated hooks can call \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` so Rescue Packs are runtime-triggered rather than relying only on instructions.
-- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
+- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps. For runtime-bound phases, capture compact rehydratable state with \`workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>\`. Then \`workflow resume\` restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
 - End substantial work with \`snipara_end_of_task_commit\` when available; for managed workflows, end every phase with \`snipara-companion workflow phase-commit\` and the task with \`snipara-companion final-commit\`. Use \`snipara_remember_if_novel\` or \`snipara_remember\` only for narrow durable memories. Never store secrets.
 `;
 }
@@ -2028,7 +2031,8 @@ function getClientGuidance(client) {
       "Codex should use the hosted MCP surface plus AGENTS.md as the canonical project instruction file.",
       "The generated .snipara/templates/codex-config.toml is a merge-ready snippet for ~/.codex/config.toml if your Codex app does not read project .codex/config.toml.",
       "Use SNIPARA_API_KEY as the only Codex bearer_token_env_var; restart Codex after changing MCP config.",
-      "If Codex lazily exposes only a minimal tool set, force discovery for snipara_recall, snipara_context_query, and snipara_settings; use snipara-companion as the fallback until Codex reloads."
+      "If Codex lazily exposes only a minimal tool set, force discovery for snipara_recall, snipara_context_query, snipara_settings, and the exact htask or swarm tool names you need; use snipara_help(list_all=true) to confirm the hosted catalog before concluding the MCP surface is incomplete.",
+      "When Codex still exposes only the minimal core tools, use snipara-orchestrator swarm-* and htask-* as the primary path for shared queues and multi-agent task work; keep snipara-companion swarm ... and htask ... as the direct hosted fallback when you only need one-off hosted calls."
     ];
   }
   if (client === "gemini") {
@@ -2137,8 +2141,8 @@ function getCompanionCommands(answers) {
     },
     {
       title: "Start a managed workflow from the visible plan",
-      command: `${COMPANION_NPX_COMMAND} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md`,
-      purpose: "Record the LLM-visible plan in .snipara/workflow/current.json so phase state survives compaction."
+      command: `${COMPANION_NPX_COMMAND} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.json`,
+      purpose: "Record the JSON machine plan in .snipara/workflow/current.json so stable phase ids survive compaction."
     },
     {
       title: "Start the current workflow phase",
@@ -2317,7 +2321,7 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 - Use \`answer_pack\` facts, caveats, source maps, and verification checks before making claims.
 - Use \`snipara_code_symbol_card\` and \`snipara_code_impact\` for important symbols or risky multi-file changes when available.
 - Use the installed \`snipara-companion\` binary for low-latency hooks; use \`${COMPANION_NPX_COMMAND}\` for one-off terminal commands when freshness matters.
-- Use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` for multi-phase work.
+- Use a JSON machine plan plus \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` for multi-phase work. After \`workflow resume\`, rerun \`workflow phase-start <phase_id>\` before editing again.
 - Persist only durable decisions, learnings, preferences, workflows, and troubleshooting outcomes. Never persist secrets.
 `;
 }
@@ -2410,7 +2414,7 @@ ${item.purpose}`
 
 - Context first: use hosted queries, shared-context, and document loads for source truth.
 - Memory second: use session bootstrap and task commit for durable decisions, learnings, and preferences.
-- Managed workflow when a visible plan exists: \`workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` keep phase state durable across compaction.
+- Managed workflow when a visible plan exists: keep the machine plan in JSON, then use \`workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` to keep phase state durable across compaction. For runtime-bound phases, use \`workflow runtime-checkpoint\` so resume can print a reattach or rehydrate path.
 - Durable memory, policy, and orchestration stay hosted in Snipara.
 - The local companion is optional tooling for capture, bootstrap, upload, exploration, doctor, repair, and explicit task summaries.
 `;
@@ -3139,7 +3143,10 @@ function printSuccess(answers, report) {
       "Restart Codex after changing ~/.codex/config.toml so it rediscovers the hosted Snipara MCP tools."
     );
     printNextStep(
-      "If Codex shows only a minimal Snipara tool set, force discovery for snipara_recall, snipara_context_query, and snipara_settings."
+      "If Codex shows only a minimal Snipara tool set, force discovery for snipara_recall, snipara_context_query, snipara_settings, and any exact htask or swarm tool names you need; confirm the hosted catalog with snipara_help(list_all=true)."
+    );
+    printNextStep(
+      "If Codex still does not expose the hosted task-routing tools, prefer snipara-orchestrator swarm-* and htask-* for shared queue or multi-agent task work, and keep snipara-companion swarm ... and htask ... as the direct hosted fallback for one-off calls."
     );
   }
   if (answers.aiClient === "mistral") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "1.3.43",
+  "version": "1.3.45",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",