@cad0p/pi-napkin 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,6 +23,7 @@ import {
23
23
  cleanupDistillWorkspace,
24
24
  cleanupStaleWorktrees,
25
25
  DistillError,
26
+ type DistillOutcome,
26
27
  findDistillErrorLogForBranch,
27
28
  findDistillOutcomeForBranch,
28
29
  getDistillState,
@@ -85,6 +86,26 @@ export function getMaxDistillDurationMs(config?: DistillConfig): number {
85
86
  return DEFAULT_MAX_DISTILL_DURATION_MS;
86
87
  }
87
88
 
89
+ /**
90
+ * Repaint cadence for the human-visible idle-status countdown rendered
91
+ * by `renderIdleStatus`. One status repaint per second keeps the
92
+ * countdown smooth ("distill in 04:32" → "04:31" → "04:30") without
93
+ * redundant work; pi's status-bar dedupes identical strings, so a tick
94
+ * that produces an unchanged status is near-zero cost. Tighter cadences
95
+ * waste cycles on dedupes; coarser cadences make the countdown jumpy.
96
+ */
97
+ const IDLE_STATUS_REPAINT_INTERVAL_MS = 1000;
98
+
99
+ /**
100
+ * Poll cadence for `runDistillWith`'s completion watcher. Balances UI
101
+ * responsiveness (sub-3-second status updates when a distill finishes)
102
+ * against wakeup cost in idle sessions where no distill is in flight.
103
+ * Race-window tests use a much tighter 50 ms tick (see
104
+ * `wrapper-invariant.test.ts`) where they need to snapshot mid-cleanup
105
+ * state; production's coarser rate is intentional.
106
+ */
107
+ const DISTILL_POLL_TICK_MS = 2000;
108
+
88
109
  /**
89
110
  * Custom entry type used to persist `/distill-auto-this-session` state into the
90
111
  * session file. CustomEntry (unlike CustomMessageEntry) does not participate in
@@ -166,7 +187,23 @@ export function loadVaultConfig(vaultPath: string): VaultConfig {
166
187
  }
167
188
  }
168
189
 
169
- const DISTILL_PROMPT = `Distill this conversation into the napkin vault.
190
+ /**
191
+ * LEGACY_DISTILL_PROMPT: used only by the legacy `spawnDistill` path
192
+ * (argv-based, pre-PR-12). The canonical agent-driven prompt lives in
193
+ * `distill-prompt.md` (loaded via `buildDistillPrompt` from
194
+ * `distill-prompt.ts`) and is the source of truth for steps 1–10 of
195
+ * the worktree distill.
196
+ *
197
+ * This constant duplicates roughly steps 1–5 of the canonical prompt
198
+ * (overview → templates → identify → search/append/create → daily
199
+ * note + supersedes frontmatter). Do NOT add new steps here without
200
+ * cross-checking distill-prompt.md — the legacy path is intentionally
201
+ * retained for git-less / disabled / legacy-embedded vaults that
202
+ * can't take the worktree spawn path, so drift between the two
203
+ * prompts is a hazard. Phase D / a future cleanup pass may factor
204
+ * the shared content into a single source.
205
+ */
206
+ const LEGACY_DISTILL_PROMPT = `Distill this conversation into the napkin vault.
170
207
 
171
208
  1. \`napkin overview\` — learn the vault structure and what exists. Read \`_about.md\` files to understand what each folder is for. These are short folder descriptions (1-2 paragraphs) explaining what kinds of notes belong there — see existing ones for style.
172
209
  2. \`napkin template list\` and \`napkin template read\` — learn the note formats.
@@ -243,7 +280,7 @@ export function spawnDistill(
243
280
  piBin,
244
281
  forkedFile,
245
282
  tmpDir,
246
- DISTILL_PROMPT,
283
+ LEGACY_DISTILL_PROMPT,
247
284
  modelStr,
248
285
  ],
249
286
  {
@@ -423,22 +460,6 @@ export default function (pi: ExtensionAPI) {
423
460
  "Auto-distill requires the subdir vault layout. See README for migration, or set distill.enabled: false in vault config.json.",
424
461
  "error",
425
462
  );
426
- } else if (setup.conflict) {
427
- // G7: existing `.gitattributes` already claims `*.md merge=<X>`.
428
- // We refuse to scaffold so we don't silently override the
429
- // user's chosen driver via last-match-wins. Explain the
430
- // options clearly — auto-distill is off for this session, but
431
- // manual /distill still works.
432
- ctx.ui.notify(
433
- [
434
- `Auto-distill setup blocked: your .gitattributes already has a merge rule for *.md ('${setup.conflict.rule}').`,
435
- "Auto-distill needs its own driver to handle concurrent distill merges safely. To enable:",
436
- ` - Remove the conflicting rule from ${setup.conflict.file}, OR`,
437
- " - Set distill.onShutdown: false in vault config.json to disable auto-distill on shutdown",
438
- "Manual /distill still works regardless.",
439
- ].join("\n"),
440
- "error",
441
- );
442
463
  } else {
443
464
  ctx.ui.notify(
444
465
  `Auto-distill setup failed: ${setup.error}. Disabling auto-distill for this session.`,
@@ -545,7 +566,7 @@ export default function (pi: ExtensionAPI) {
545
566
  // `renderIdleStatus` self-guards against in-flight distills; when off
546
567
  // it paints `distill: off (session)` (pi dedupes identical status strings).
547
568
  renderIdleStatus();
548
- }, 1000);
569
+ }, IDLE_STATUS_REPAINT_INTERVAL_MS);
549
570
  }
550
571
 
551
572
  intervalHandle = setInterval(() => {
@@ -627,7 +648,9 @@ export default function (pi: ExtensionAPI) {
627
648
  vault: vaultInfo.contentPath,
628
649
  sessionFile,
629
650
  parentCwd: ctx.cwd,
630
- prompt: DISTILL_PROMPT,
651
+ maxDurationSecs: Math.round(
652
+ getMaxDistillDurationMs(config) / 1000,
653
+ ),
631
654
  model: modelStr,
632
655
  });
633
656
  // Mark this size as "spawned" so if the parent re-enters shutdown
@@ -751,8 +774,8 @@ export default function (pi: ExtensionAPI) {
751
774
  /**
752
775
  * Optional probe invoked when `target` disappears AND `checkFailure`
753
776
  * returned null (no fatal error). Returns the wrapper-emitted
754
- * outcome sidecar (POST-CONV-5): `{ outcomeClass, outcomePath,
755
- * partialMergeLogPath }` when present, null when missing.
777
+ * outcome sidecar (POST-CONV-5) as a `DistillOutcome` (see
778
+ * `distill-workspace.ts`) when present, null when missing.
756
779
  *
757
780
  * Missing sidecar AND missing failure log = abnormal termination
758
781
  * (SIGKILL / `set -e` / disk full / race) — the runner surfaces
@@ -760,11 +783,7 @@ export default function (pi: ExtensionAPI) {
760
783
  * contract. Legacy spawn doesn't produce outcome sidecars — omit
761
784
  * or return null.
762
785
  */
763
- checkOutcome?: () => {
764
- outcomeClass: string;
765
- outcomePath: string;
766
- partialMergeLogPath: string | null;
767
- } | null;
786
+ checkOutcome?: () => DistillOutcome | null;
768
787
  } | null;
769
788
  }
770
789
 
@@ -997,11 +1016,11 @@ export default function (pi: ExtensionAPI) {
997
1016
  // Wrapper-failure check (R7-SC-3). Mirrors the timeout-surfacing
998
1017
  // pattern: target disappearance is the success condition, but the
999
1018
  // wrapper writes a forensic log on any non-success exit (missing
1000
- // napkin, pi subprocess error, merge-driver 3-strike, etc.). If a
1001
- // log file matching this distill's branch is present in the
1002
- // error dir, the run failed even though the worktree is gone.
1003
- // Surface the failure in the UI so the user can act on it instead
1004
- // of the run silently disappearing.
1019
+ // napkin, pi subprocess error, agent timeout, post-call validation
1020
+ // failure, etc.). If a log file matching this distill's branch is
1021
+ // present in the error dir, the run failed even though the worktree
1022
+ // is gone. Surface the failure in the UI so the user can act on it
1023
+ // instead of the run silently disappearing.
1005
1024
  let failureLogPath: string | null = null;
1006
1025
  if (checkFailure) {
1007
1026
  try {
@@ -1046,11 +1065,7 @@ export default function (pi: ExtensionAPI) {
1046
1065
  // full mapping. Strategies that don't produce sidecars (legacy
1047
1066
  // /distill on git-less or disabled vaults) skip this entire
1048
1067
  // dispatch and fall through to the default info notification.
1049
- let outcome: {
1050
- outcomeClass: string;
1051
- outcomePath: string;
1052
- partialMergeLogPath: string | null;
1053
- } | null = null;
1068
+ let outcome: DistillOutcome | null = null;
1054
1069
  if (checkOutcome) {
1055
1070
  try {
1056
1071
  outcome = checkOutcome();
@@ -1069,13 +1084,6 @@ export default function (pi: ExtensionAPI) {
1069
1084
  const dispatch = formatOutcomeNotification({
1070
1085
  outcome,
1071
1086
  elapsedSec: elapsed,
1072
- readPartialMergeLog: (p) => {
1073
- try {
1074
- return fs.readFileSync(p, "utf-8");
1075
- } catch {
1076
- return null;
1077
- }
1078
- },
1079
1087
  });
1080
1088
  level = dispatch.level;
1081
1089
  message = dispatch.message;
@@ -1091,7 +1099,7 @@ export default function (pi: ExtensionAPI) {
1091
1099
  }
1092
1100
  ctx.ui.notify(message, level);
1093
1101
  }
1094
- }, 2000);
1102
+ }, DISTILL_POLL_TICK_MS);
1095
1103
  }
1096
1104
 
1097
1105
  function runDistill(ctx: RunCtx) {
@@ -1101,9 +1109,8 @@ export default function (pi: ExtensionAPI) {
1101
1109
  // back to the legacy tmpdir spawn, which has zero git side effects.
1102
1110
  //
1103
1111
  // `distill.enabled=false` means the user opted out of auto-distill's
1104
- // infrastructure (including `.gitattributes` rewrites). Worktree
1105
- // spawn calls `registerMergeDriver()` which writes git config; legacy
1106
- // path doesn't.
1112
+ // infrastructure (worktree-based concurrency, scaffolded `.gitignore`,
1113
+ // session-fork housekeeping). Legacy path bypasses all of it.
1107
1114
  //
1108
1115
  // Legacy-embedded layout (`configPath === contentPath`) forces the
1109
1116
  // same fallback: the worktree path silently corrupts on that layout
@@ -1117,7 +1124,8 @@ export default function (pi: ExtensionAPI) {
1117
1124
  // worktree isolation — two concurrent `/distill` calls on a git-less,
1118
1125
  // disabled, or legacy-embedded vault race on napkin writes. With
1119
1126
  // git + enabled + subdir layout, both manual and auto paths serialize
1120
- // through the merge driver.
1127
+ // through per-distill worktrees, and the agent owns merge resolution
1128
+ // end-to-end (PR #12).
1121
1129
  runDistillWith(ctx, {
1122
1130
  spawnFn: (args) => {
1123
1131
  const gitPresent = fs.existsSync(
@@ -1137,10 +1145,11 @@ export default function (pi: ExtensionAPI) {
1137
1145
  /**
1138
1146
  * Worktree-backed auto-distill path — used by the interval timer and the
1139
1147
  * shutdown handler (Item 8). Concurrency-safe via per-distill git
1140
- * worktrees: each call spawns a detached wrapper that operates on its
1141
- * own branch, so overlapping distills (interval + shutdown, or multiple
1142
- * pi sessions on the same vault) merge serially on main via the LLM
1143
- * merge driver.
1148
+ * worktrees: each call spawns a detached wrapper that drives the agent
1149
+ * to distill, merge default into its branch, squash to default, and
1150
+ * push — so overlapping distills (interval + shutdown, or multiple pi
1151
+ * sessions on the same vault) integrate serially through the agent's
1152
+ * own merge resolution rather than colliding on main.
1144
1153
  */
1145
1154
  function runAutoDistill(ctx: RunCtx) {
1146
1155
  runDistillWith(ctx, {
@@ -1190,14 +1199,17 @@ export default function (pi: ExtensionAPI) {
1190
1199
 
1191
1200
  /**
1192
1201
  * Worktree spawn strategy. Creates a per-distill git worktree off the
1193
- * vault's default branch, runs the detached wrapper that merges back
1194
- * via the LLM merge driver + squash. Concurrency-safe across sessions.
1202
+ * vault's default branch, then runs the detached wrapper that hands a
1203
+ * full distill→merge→squash→push contract to the agent (see
1204
+ * `distill-prompt.md` and design.md "Locked decisions"). Wrapper
1205
+ * post-validates the agent's output (markers, commit count, HEAD) and
1206
+ * salvages the worktree on failure. Concurrency-safe across sessions.
1195
1207
  *
1196
1208
  * Shared by `runDistill` (when git is available) and `runAutoDistill`.
1197
1209
  * A `DistillError` from the workspace layer (branch collision, fork
1198
- * failure, invalid HEAD, merge driver missing) is caught and rendered
1199
- * as an error status; the shared runner treats a null return as a
1200
- * spawn failure and skips the poll loop.
1210
+ * failure, invalid HEAD) is caught and rendered as an error status; the
1211
+ * shared runner treats a null return as a spawn failure and skips the
1212
+ * poll loop.
1201
1213
  */
1202
1214
  function worktreeSpawnFn(args: {
1203
1215
  ctx: RunCtx;
@@ -1210,11 +1222,7 @@ export default function (pi: ExtensionAPI) {
1210
1222
  cleanup: () => void;
1211
1223
  onComplete?: (ctx: RunCtx) => void;
1212
1224
  checkFailure?: () => string | null;
1213
- checkOutcome?: () => {
1214
- outcomeClass: string;
1215
- outcomePath: string;
1216
- partialMergeLogPath: string | null;
1217
- } | null;
1225
+ checkOutcome?: () => DistillOutcome | null;
1218
1226
  } | null {
1219
1227
  const { ctx: c, vaultContentPath, sessionFile, config } = args;
1220
1228
  try {
@@ -1225,7 +1233,7 @@ export default function (pi: ExtensionAPI) {
1225
1233
  vault: vaultContentPath,
1226
1234
  sessionFile,
1227
1235
  parentCwd: c.cwd,
1228
- prompt: DISTILL_PROMPT,
1236
+ maxDurationSecs: Math.round(getMaxDistillDurationMs(config) / 1000),
1229
1237
  model: modelStr,
1230
1238
  });
1231
1239
  // Capture startSha so the completion handler can diff post-squash
@@ -1663,19 +1671,16 @@ export function formatOverlapNotice(overlapFiles: string[]): string {
1663
1671
  * dispatches to `ctx.ui.notify` / `ctx.ui.setStatus`.
1664
1672
  *
1665
1673
  * Inputs:
1666
- * - `outcome`: the parsed sidecar (`{ outcomeClass, partialMergeLogPath }`)
1674
+ * - `outcome`: the parsed sidecar (`{ outcomeClass, recoveryHint }`)
1667
1675
  * or null when no sidecar exists at all (abnormal termination).
1668
1676
  * - `elapsedSec`: wall-clock seconds since spawn, used in the
1669
1677
  * default success message (`merged-content`).
1670
- * - `readPartialMergeLog`: optional reader injected for testability.
1671
- * Returns the log content as a string, or
1672
- * null on read failure. Production passes
1673
- * an `fs.readFileSync` wrapper.
1674
1678
  *
1675
1679
  * Outputs `{ level, message, statusKey, statusText }` per class:
1676
1680
  * merged-content → info / "Distillation complete (Ns)"
1681
+ * merged-local → warn / "Distillation complete locally; not pushed to origin"
1677
1682
  * no-content → warn / "Distillation ran but saved no content"
1678
- * partial-merge → warn / "Distillation: partial merge — N file(s) reverted to main; see <log>"
1683
+ * failed:<reason> → error / "Distillation failed: <reason> [— <hint>]"
1679
1684
  * <unknown> → warn / defensive class string
1680
1685
  * missing sidecar → warn / "Distillation terminated abnormally — no outcome record"
1681
1686
  *
@@ -1685,12 +1690,8 @@ export function formatOverlapNotice(overlapFiles: string[]): string {
1685
1690
  * Exported for unit tests; production wiring lives in `runDistillWith`.
1686
1691
  */
1687
1692
  export function formatOutcomeNotification(args: {
1688
- outcome: {
1689
- outcomeClass: string;
1690
- partialMergeLogPath: string | null;
1691
- } | null;
1693
+ outcome: Pick<DistillOutcome, "outcomeClass" | "recoveryHint"> | null;
1692
1694
  elapsedSec: number;
1693
- readPartialMergeLog?: (path: string) => string | null;
1694
1695
  }): {
1695
1696
  level: "info" | "warning" | "error";
1696
1697
  message: string;
@@ -1698,7 +1699,7 @@ export function formatOutcomeNotification(args: {
1698
1699
  statusGlyph: string;
1699
1700
  statusText: string;
1700
1701
  } {
1701
- const { outcome, elapsedSec, readPartialMergeLog } = args;
1702
+ const { outcome, elapsedSec } = args;
1702
1703
  if (!outcome) {
1703
1704
  return {
1704
1705
  level: "warning",
@@ -1717,36 +1718,54 @@ export function formatOutcomeNotification(args: {
1717
1718
  statusGlyph: "✓",
1718
1719
  statusText: ` distill ${elapsedSec}s`,
1719
1720
  };
1720
- case "no-content":
1721
+ case "merged-local":
1722
+ // PR #12: agent landed content on main but origin wasn't reached
1723
+ // (push failed, network down, or origin moved and the agent gave
1724
+ // up rather than loop indefinitely). Local main is ahead of
1725
+ // origin/<default>. User must push manually or wait for the next
1726
+ // distill's push to carry both forward. Surface as `warning` per
1727
+ // the locked notification severity contract.
1721
1728
  return {
1722
1729
  level: "warning",
1723
- message: "Distillation ran but saved no content",
1730
+ message: `Distillation complete locally; not pushed to origin (${elapsedSec}s)`,
1724
1731
  statusKey: "warning",
1725
1732
  statusGlyph: "⚠",
1726
- statusText: " distill: no content",
1733
+ statusText: " distill: local-only",
1727
1734
  };
1728
- case "partial-merge": {
1729
- let revertedCount = 0;
1730
- if (outcome.partialMergeLogPath && readPartialMergeLog) {
1731
- const content = readPartialMergeLog(outcome.partialMergeLogPath);
1732
- if (content) {
1733
- revertedCount = content
1734
- .split("\n")
1735
- .filter((line) => /\breverted '/.test(line)).length;
1736
- }
1737
- }
1738
- const message = outcome.partialMergeLogPath
1739
- ? `Distillation: partial merge — ${revertedCount} file${revertedCount === 1 ? "" : "s"} reverted to main; see ${outcome.partialMergeLogPath}`
1740
- : "Distillation: partial merge — some files reverted to main";
1735
+ case "no-content":
1741
1736
  return {
1742
1737
  level: "warning",
1743
- message,
1738
+ message: "Distillation ran but saved no content",
1744
1739
  statusKey: "warning",
1745
1740
  statusGlyph: "⚠",
1746
- statusText: " distill: partial",
1741
+ statusText: " distill: no content",
1747
1742
  };
1748
- }
1749
- default:
1743
+ default: {
1744
+ // PR #12: `failed:<reason>` carries a reason code identifying
1745
+ // which validator tripped (markers-after-agent-exit,
1746
+ // pre-existing-markers, head-not-on-default, agent-exit-nonzero,
1747
+ // agent-timeout, divergent-history). Surface as `error` with the
1748
+ // reason in
1749
+ // the message so the user can diagnose without opening the
1750
+ // error log first.
1751
+ //
1752
+ // PR #12 A4: when the wrapper's salvage path emitted a recovery
1753
+ // hint into the outcome sidecar (lines 2+), append it to the
1754
+ // notification message so the user sees the recommended
1755
+ // `git revert` / `git reflog` recovery action inline.
1756
+ if (outcome.outcomeClass.startsWith("failed:")) {
1757
+ const reason = outcome.outcomeClass.slice("failed:".length);
1758
+ const message = outcome.recoveryHint
1759
+ ? `Distillation failed: ${reason} — ${outcome.recoveryHint}`
1760
+ : `Distillation failed: ${reason}`;
1761
+ return {
1762
+ level: "error",
1763
+ message,
1764
+ statusKey: "error",
1765
+ statusGlyph: "✗",
1766
+ statusText: ` distill: ${reason}`,
1767
+ };
1768
+ }
1750
1769
  return {
1751
1770
  level: "warning",
1752
1771
  message: `Distillation: unrecognised outcome '${outcome.outcomeClass}'`,
@@ -1754,6 +1773,7 @@ export function formatOutcomeNotification(args: {
1754
1773
  statusGlyph: "⚠",
1755
1774
  statusText: " distill: unknown outcome",
1756
1775
  };
1776
+ }
1757
1777
  }
1758
1778
  }
1759
1779