pi-posthorse 0.10.15 → 0.10.17

package/README.md

@@ -35,6 +35,8 @@ See the [changelog](https://github.com/fitchmultz/pi-posthorse/blob/main/CHANGEL
 
 Recoverable history is not guaranteed model recall. See the [practical guarantees and limits](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/context-recovery.md) for the stock-Pi comparison, search scope, checkpoints, privacy, concurrency and cost, or the [rollover reference](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/reference.md#how-it-works) for implementation details.
 
+The [field study](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/field-study.md) measures what agents did around 24,940 context boundaries in daily use: note and history use, repeated work, stops, wait time, and cost. It is observational, not a controlled comparison with stock compaction.
+
 ## Tools
 
 These tools are available to the model:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.15",
+	"version": "0.10.17",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [

package/src/budget.ts

@@ -79,7 +79,7 @@ function automaticGuidance(budget: Budget | undefined, enabled: boolean): string
 			? ""
 			: `The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used. `;
 	return `Pi rolls context over automatically, so the context window is not a deadline. Do not reduce scope, skip steps or verification, or write a final summary because rollover is near, and do not wait for the user to say "continue". Finish when the requested work and its verification are complete, or report a genuine blocker.
-${line}Rollover keeps a recent-message tail without summarizing. One task-note reminder may arrive at the end of a working turn near the line: update the note only if it is stale, then continue with the next step in the same run. new_context is an optional clean reset.`;
+${line}Rollover keeps a recent-message tail without summarizing. One task-note reminder may arrive at the end of a working turn near the line: update the note only if it is stale, or write one if the task has none, then continue with the next step in the same run. new_context is an optional clean reset.`;
 }
 export function buildGuidance(ctx: PolicyContext): string {
 	const budget = budgetFor(ctx);

package/src/note-store.ts

@@ -129,7 +129,7 @@ export class SessionNotes {
 			return manifest;
 		}
 		throw new Error(
-			`Unknown notes scope ${selector}. Copy a scope selector from notes list/search.`,
+			`Unknown notes scope ${JSON.stringify(selector)}. Omit scope for this session's notes, or copy a scope selector from notes list/search.`,
 		);
 	}
 	async #reference(path: string, signal?: AbortSignal): Promise<NoteAddress | undefined> {

package/src/notes.ts

@@ -278,6 +278,11 @@ async function searchNotes(
 		header: hits.skipped > 0 ? `[Not searched: ${skipped} over 1 MiB.]\n` : "",
 	});
 }
+/** Some models send every optional argument; an empty scope means no scope. */
+function withoutEmptyScope(params: NotesParams): NotesParams {
+	const { scope, ...unscoped } = params;
+	return scope === "" ? unscoped : params;
+}
 export function registerNotes(
 	pi: ExtensionAPI,
 	policy: (ctx: ExtensionContext) => PolicyContext,
@@ -325,7 +330,8 @@ export function registerNotes(
 				}),
 			),
 		}),
-		async execute(...[_id, params, signal, , ctx]) {
+		async execute(...[_id, received, signal, , ctx]) {
+			const params = withoutEmptyScope(received);
 			// Migrate newly returned legacy package notes without changing this session’s binding.
 			notesDir(ctx.cwd);
 			const session = await store.get(ctx);

package/src/recovery-note-touches.ts

@@ -262,8 +262,9 @@ function notesToolTouches(
 	const parsed = resultText === undefined ? undefined : extractNotesResultTarget(resultText);
 	const kind = notesCallKind(args) ?? parsed?.kind;
 	const path = optionalString(args.path);
-	const scopedPath =
-		typeof args.scope === "string" && path !== undefined ? `${args.scope}/${path}` : path;
+	// An empty scope counts as omitted, as it does when the tool runs.
+	const scope = args.scope === "" ? undefined : optionalString(args.scope);
+	const scopedPath = scope !== undefined && path !== undefined ? `${scope}/${path}` : path;
 	const callTarget = resolveNoteTarget(scopedPath, context.knownDirs, true);
 	const resTarget = resolveNoteTarget(parsed?.rawPath, context.knownDirs, true);
 	const merged = mergeNoteTargets(callTarget, resTarget);

package/src/recovery-notes.ts

@@ -77,22 +77,39 @@ function applyTouch(
 		order,
 	};
 }
-function formatNoteLabel(note: TrackedNote): string {
+/** `notes read` resolves a bare name in this session's own notes, so a note elsewhere is named by its path. */
+function pathElsewhere(note: TrackedNote, notesDirectory: string | undefined): string | undefined {
 	if (note.referenceScope !== undefined) {
-		return `${note.notePath} (another notes scope: ${note.absPath ?? `${note.referenceScope}/${note.notePath}`})`;
+		return note.absPath ?? `${note.referenceScope}/${note.notePath}`;
+	}
+	return note.absPath !== undefined &&
+		notesDirectory !== undefined &&
+		note.absPath !== join(notesDirectory, note.notePath)
+		? note.absPath
+		: undefined;
+}
+function formatNoteLabel(note: TrackedNote, elsewhere: string | undefined): string {
+	if (elsewhere !== undefined) {
+		return note.referenceScope === undefined ? elsewhere : `${elsewhere} (another notes scope)`;
 	}
 	return note.absPath !== undefined && note.absPath !== note.notePath
 		? `${note.notePath} (${note.absPath})`
 		: note.notePath;
 }
-function formatWrittenNoteLine(note: WrittenNote, span: RetainedSpan | undefined): string {
-	const label = formatNoteLabel(note);
+function formatWrittenNoteLine(
+	note: WrittenNote,
+	span: RetainedSpan | undefined,
+	notesDirectory: string | undefined,
+): string {
+	const elsewhere = pathElsewhere(note, notesDirectory);
+	const label = formatNoteLabel(note, elsewhere);
+	const how = elsewhere === undefined ? "" : " on its path";
 	const { proof } = note;
 	if (proof.kind === "effect-only") {
-		return `- Active note (written): ${label} [verified effect at entry ${note.entryId}; full content is not retained — read this note now]`;
+		return `- Active note (written): ${label} [verified effect at entry ${note.entryId}; full content is not retained — read this note${how} now]`;
 	}
 	if (span === undefined) {
-		return `- Active note (written): ${label} [compacted at entry ${note.entryId} — read this note now]`;
+		return `- Active note (written): ${label} [compacted at entry ${note.entryId} — read this note${how} now]`;
 	}
 	switch (proof.kind) {
 		case "full": {
@@ -101,13 +118,17 @@ function formatWrittenNoteLine(note: WrittenNote, span: RetainedSpan | undefined
 			return `- Active note (written): ${label} [latest full write is in the retained tail above at entry ${proof.entryId}${updated}]`;
 		}
 		case "partial":
-			return `- Active note (written): ${label} [only partial edits are in the retained tail above at entry ${proof.entryId} — read full note now]`;
+			return `- Active note (written): ${label} [only partial edits are in the retained tail above at entry ${proof.entryId} — read full note${how} now]`;
 		case "compacted":
-			return `- Active note (written): ${label} [compacted before entry ${span.firstId} — read this note now]`;
+			return `- Active note (written): ${label} [compacted before entry ${span.firstId} — read this note${how} now]`;
 	}
 }
-function formatReadNoteLine(note: ReadNote, span: RetainedSpan | undefined): string {
-	const label = formatNoteLabel(note);
+function formatReadNoteLine(
+	note: ReadNote,
+	span: RetainedSpan | undefined,
+	notesDirectory: string | undefined,
+): string {
+	const label = formatNoteLabel(note, pathElsewhere(note, notesDirectory));
 	if (span !== undefined && note.inRetained) {
 		return `- Referenced note (read): ${label} [read in the retained tail above at entry ${note.entryId}]`;
 	}
@@ -123,16 +144,12 @@ function formatNotesAction(
 	if (primaryWritten === undefined) {
 		return "Read the referenced note again if its context is still needed, and keep one current-state note for this task.";
 	}
-	// notes read resolves a bare name in this session's own scope, so a note elsewhere is named by its path.
-	const elsewhere =
-		primaryWritten.absPath !== undefined &&
-		notesDirectory !== undefined &&
-		primaryWritten.absPath !== join(notesDirectory, primaryWritten.notePath);
-	const target = elsewhere ? primaryWritten.absPath : primaryWritten.notePath;
+	const elsewhere = pathElsewhere(primaryWritten, notesDirectory);
+	const target = elsewhere ?? primaryWritten.notePath;
 	if (span !== undefined && primaryWritten.proof.kind === "full") {
 		return `Your latest full write to ${target} is already visible above at entry ${primaryWritten.proof.entryId}; do not rewrite it unless new findings after entry ${span.lastId} require it.`;
 	}
-	const how = elsewhere ? "read on its path" : "notes read or read on its path";
+	const how = elsewhere === undefined ? "notes read or read on its path" : "read on its path";
 	return `Read ${target} (${how}) before continuing to restore the saved goal, progress, decisions, and next steps, then keep that note current as work progresses.`;
 }
 function trackedNotes(
@@ -181,16 +198,14 @@ export function renderSessionNotes(
 	}
 	const written = all.filter((note) => note.kind === "written").slice(0, MAX_WRITTEN_NOTES);
 	const readOnly = all.filter((note) => note.kind === "read").slice(0, MAX_READ_NOTES);
+	const notesDirectory =
+		options.notes === undefined ? defaultDir : scopeDirectory(options.notes.binding);
 	const lines = [
-		...written.map((note) => formatWrittenNoteLine(note, span)),
-		...readOnly.map((note) => formatReadNoteLine(note, span)),
+		...written.map((note) => formatWrittenNoteLine(note, span, notesDirectory)),
+		...readOnly.map((note) => formatReadNoteLine(note, span, notesDirectory)),
 	];
 	const header = "Task notes in this session:";
-	const action = formatNotesAction(
-		written[0],
-		span,
-		options.notes === undefined ? defaultDir : scopeDirectory(options.notes.binding),
-	);
+	const action = formatNotesAction(written[0], span, notesDirectory);
 	const selected: string[] = [];
 	for (const line of lines) {
 		if ([header, ...selected, line, action].join("\n").length <= maxChars) {

package/src/rollover.ts

@@ -445,7 +445,7 @@ export function registerRollover(
 				{
 					customType: REMINDER_TYPE,
 					content:
-						"[posthorse] Routine task-note update. Update the task's current-state note if it is stale, then continue with the next step in this run.",
+						"[posthorse] Routine task-note update. Update the task's current-state note if it is stale, or write one if the task has none, then continue with the next step in this run.",
 					display: true,
 					details: reminder.fingerprint,
 				},