substrate-ai 0.20.102 → 0.20.104

package/dist/cli/index.js

@@ -2089,6 +2089,10 @@ async function runInitAction(options) {
 			".substrate/current-run-id",
 			".substrate/scenarios/",
 			".substrate/state/",
+			".substrate/runs/",
+			".substrate/notifications/",
+			".substrate/kv-metrics.json",
+			".substrate/latest-heartbeat-per-story-state.json",
 			".substrate/substrate.db",
 			".substrate/substrate.db-journal",
 			".codex/prompts/",
@@ -11951,8 +11955,9 @@ function registerIngestEpicCommand(program) {
 			await initWorkGraphSchema(adapter);
 			const ingester = new EpicIngester(adapter);
 			const result = await ingester.ingest(stories, dependencies);
-			const epicNum = stories[0].epic_num;
-			process.stdout.write(`Ingested ${result.storiesUpserted} stories and ${result.dependenciesReplaced} dependencies from epic ${epicNum}\n`);
+			const epicNums = [...new Set(stories.map((s) => s.epic_num))].sort((a, b) => a - b);
+			const epicLabel = epicNums.length === 1 ? `epic ${epicNums[0]}` : `epics ${epicNums.join(", ")}`;
+			process.stdout.write(`Ingested ${result.storiesUpserted} stories and ${result.dependenciesReplaced} dependencies from ${epicLabel}\n`);
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`Error: ${msg}\n`);

package/dist/cli/templates/agents-md-substrate-section.md

@@ -93,4 +93,14 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
 - `.substrate/current-run-id` — plain text file with the latest run ID
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
+
+### Recommended `.gitignore` entries
+
+Substrate writes ephemeral per-process and per-run state under `.substrate/`. Only `.substrate/config.yaml` is intended to be tracked — everything else (Dolt repo, kv-metrics, run manifests, heartbeats, halt notifications, current-run-id, .pid files) regenerates each run. Ignore everything under `.substrate/` and re-include only the config:
+
+```gitignore
+# Substrate ephemeral state — track only the operator config
+.substrate/*
+!.substrate/config.yaml
+```
 <!-- substrate:end -->

package/dist/cli/templates/claude-md-substrate-section.md

@@ -109,6 +109,30 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/current-run-id` — plain text file with the latest run ID; consulted by canonical run-discovery
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications written by the Recovery Engine; deleted by `substrate report` after read
 
+### Recommended `.gitignore` entries
+
+Substrate writes ephemeral per-process and per-run state under `.substrate/`. Only `.substrate/config.yaml` is intended to be tracked — everything else (the Dolt repo, kv-metrics, run manifests, heartbeats, halt notifications, current-run-id, .pid files) is regenerated each run and should be ignored. The simplest pattern is to ignore everything under `.substrate/` and re-include only the config:
+
+```gitignore
+# Substrate ephemeral state — track only the operator config
+.substrate/*
+!.substrate/config.yaml
+```
+
+This is future-proof against new ephemeral files substrate may introduce. If you'd rather enumerate the specific patterns, the equivalent explicit form is:
+
+```gitignore
+.substrate/state/
+.substrate/runs/
+.substrate/notifications/
+.substrate/kv-metrics.json
+.substrate/current-run-id
+.substrate/latest-heartbeat-per-story-state.json
+.substrate/*.db
+.substrate/*.pid
+.substrate/routing-policy.yaml
+```
+
 ### State Backend
 
 Substrate uses Dolt for versioned pipeline state by default. Run `substrate init` to set it up automatically if Dolt is on PATH. Features that require Dolt: `substrate history`, OTEL observability persistence, and context engineering repo-map storage.

package/dist/cli/templates/gemini-md-substrate-section.md

@@ -93,4 +93,14 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
 - `.substrate/current-run-id` — plain text file with the latest run ID
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
+
+### Recommended `.gitignore` entries
+
+Substrate writes ephemeral per-process and per-run state under `.substrate/`. Only `.substrate/config.yaml` is intended to be tracked — everything else (Dolt repo, kv-metrics, run manifests, heartbeats, halt notifications, current-run-id, .pid files) regenerates each run. Ignore everything under `.substrate/` and re-include only the config:
+
+```gitignore
+# Substrate ephemeral state — track only the operator config
+.substrate/*
+!.substrate/config.yaml
+```
 <!-- substrate:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.20.102",
+  "version": "0.20.104",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",