@machine-made/pi-rethread 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+### Added
+- `/rethread [goal]`: the agent lands its step, writes a letter to the next session and a ledger entry (`rethread_save` tool), then a new session opens with the letter and asks for a three-line readback.
+- `/rethread --now` (side model call writes the handoff), `--review` (edit before moving), `--cancel`.
+- `/ledger` shows the ledger file and its entry count.
+- Automatic rethread at `--rethread-auto-percent` (default 70) and instead of Pi's automatic compaction; once per session, with a loop guard.
+- The four prompts are Markdown templates; a project can override each one in `.pi/rethread/`.
+
+### Fixed (before the first release)
+- A reply that went past the whole context window let Pi compact the old session in the middle of the handoff, so the agent wrote its letter from a lossy summary. Only Pi's recovery of a rejected request (which must retry) may compact now.
+- The integration tests read `~/.agents/skills` and `PI_*` variables from the real environment, so their result depended on the machine. Each Pi now runs with an empty home.

package/LICENSE

@@ -0,0 +1,111 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works,
+that is intentionally submitted to Licensor for inclusion in the Work by the
+copyright owner or by an individual or Legal Entity authorized to submit on
+behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any
+Contributor be liable to You for damages, including any direct, indirect,
+special, incidental, or consequential damages arising as a result of this
+License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Ricardo Frantz

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# pi-rethread
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Extension for [pi](https://github.com/earendil-works/pi): when a session gets long, the agent finishes its step, writes a **letter** to the next session and a **ledger** entry, and the work continues in a **fresh session**. No lossy compaction.
+
+```text
+pi install npm:@machine-made/pi-rethread
+```
+
+Tested with Pi 1.4.0.
+
+## Commands
+
+```text
+/rethread [goal]     finish, hand off, continue in a new session
+/rethread --now      skip the agent (it is stuck): a side model call writes the handoff
+/rethread --review   edit the ledger entry before moving (interactive only)
+/rethread --cancel   stop a rethread in progress
+/ledger              show the ledger file and its number of entries
+```
+
+## What happens
+
+`/rethread` runs four prepared messages, each doing one job:
+
+1. **Land.** The running agent finishes the step it is on and stops at a safe point: no half-edited
+   file, no new work, the quick check (tests, build) run once. It replies in three lines: what is
+   *verified*, what is only *assumed*, what is still broken.
+2. **Letter.** The agent writes to the agent of the next session, in a fixed shape:
+   *Where we are*, *Do first*, *Watch out*, *Don't redo* (dead ends, so they are not tried again)
+   and *Trust* (verified vs assumed). The letter comes first: writing to a colleague forces priorities.
+3. **Ledger.** In the same tool call, after the letter, the agent writes the durable facts:
+   Goal, Done, Decisions, Files, Commands, Open problems, Next steps. The letter is intent for the
+   next hop; the ledger is what stays true across many hops. It is appended to `.pi/ledger.md`.
+4. **Readback.** A new session opens (linked to the old one as its parent) and receives the letter
+   and the ledger entry. Its first reply is three lines: the goal, the first action, the main risk.
+   A misunderstanding costs one short reply instead of a whole run.
+
+The `rethread_save` tool is shown to the model only during step 2.
+
+If the agent does not call the tool, a side model call writes the letter and the ledger from the
+transcript instead, and the move still happens.
+
+## Automatic
+
+After a run, if context use is at or above `--rethread-auto-percent` (default 70), `/rethread`
+starts by itself. When Pi would auto-compact first, the compaction is cancelled and a rethread
+runs instead. This covers Pi's threshold and a reply that silently went past the window. No
+automatic compaction touches the old session while the agent writes its handoff.
+
+Left alone: manual `/compact`, and Pi's recovery when the provider rejects a request as too long.
+That recovery compacts and retries the failed turn; without it the turn cannot run. The rethread
+then continues, and the agent writes its letter from the compacted session.
+
+It fires once per session. If a new session is already over the limit right after the handoff
+(a low limit, a long ledger), the automatic rethread turns itself off for that session and says so,
+so it never loops.
+
+## Flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--rethread-auto-percent <n>` | `70` | Context % that starts `/rethread`; `0` turns the automatic rethread off |
+| `--ledger-file <path>` | `.pi/ledger.md` | Ledger file, relative to the working directory |
+
+## Your own prompts
+
+The four messages are Markdown templates in [`prompts/`](prompts). Put a file with the same name in
+`.pi/rethread/` of a project to replace one there:
+
+| File | Sent to | Placeholders |
+|---|---|---|
+| `land.md` | the old agent, step 1 | none |
+| `write.md` | the old agent, step 2 | `{{tool}}` `{{headings}}` `{{goal_line}}` `{{previous}}` |
+| `kickoff.md` | the new agent, step 4 | `{{ledger_path}}` `{{letter}}` `{{goal_line}}` `{{status}}` `{{ledger}}` |
+| `summary.md` | the side model (`--now`, fallback) | `{{headings}}` |
+
+A custom `kickoff.md` must keep a `<rethread-ledger>` tag: it is how the new session knows it was
+started by a rethread (for the loop guard).
+
+## The ledger
+
+`.pi/ledger.md` is plain Markdown, newest entry last. Each entry records the old session file, the
+status (`landed`, `partial`, `blocked`), who wrote it (the agent or a summary), the goal, the ledger
+sections and the letter. The file is written atomically. Commit it, or add it to `.gitignore`.
+
+## Limits
+
+- A `/rethread --cancel` typed in the instant between two steps is queued behind the next step;
+  type it again.
+- The new session uses the same model and tools as the old one.
+
+## Development
+
+```text
+bun install
+bun run check
+bun run test
+```
+
+The integration test runs real Pi in RPC mode with a scripted fake model, so it needs no API key.
+
+## Licence
+
+Apache-2.0

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security
+
+pi-rethread has not had a security review yet.
+
+What it does: it reads and writes one Markdown file (`.pi/ledger.md`, or the path given by
+`--ledger-file`), reads prompt templates from the package and from `.pi/rethread/` in the working
+directory, sends prompts to the session's own model, and opens a new Pi session. It makes no network
+call of its own and spawns no process.
+
+Things to know:
+- The ledger and the letter are written by the model and sent to the next session as a user message.
+  Treat them like any other model output: review the ledger if the session handled untrusted input.
+- Project templates in `.pi/rethread/` change what is sent to the model, and they are read from
+  the working directory whoever wrote them. Check that folder in a repository you did not write.
+
+Report issues at https://github.com/machine-made/pi-rethread/issues

package/index.ts

@@ -0,0 +1,375 @@
+/**
+ * pi-rethread — end this session cleanly and continue in a new one.
+ *
+ *   /rethread [goal]     1. land:  the agent finishes its step and says what is verified
+ *                        2. write: the agent writes a letter to the next session, then a ledger entry
+ *                        3. move:  the ledger is appended, a new session opens with the letter
+ *                        4. readback: the new agent restates goal, first action, main risk, then starts
+ *   /rethread --now      skip 1-2 (agent stuck): a side model call writes letter + ledger
+ *   /rethread --review   edit the ledger entry before moving (interactive only)
+ *   /rethread --cancel   abort a rethread in progress
+ *   /ledger              show the ledger path and entry count
+ *
+ * Automatic: after a run settles at or above --rethread-auto-percent of the context window, or when
+ * Pi would auto-compact, /rethread starts by itself (once per session; never loops).
+ *
+ * The session switch uses Pi's documented API (ctx.newSession + withSession), as in Pi's
+ * examples/extensions/handoff.ts.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { type Message, StringEnum, uuidv7 } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	appendEntry,
+	entryLedger,
+	fill,
+	goalLine,
+	type Handoff,
+	headingsList,
+	isKickoff,
+	loadTemplate,
+	looksLikeLedger,
+	parseArgs,
+	parseThreshold,
+	readEntries,
+	resolveLedgerPath,
+	STATUSES,
+	type Status,
+	shownPath,
+	splitSummary,
+	TOOL_NAME,
+	USAGE,
+} from "./rethread.ts";
+
+type Phase = "idle" | "land" | "write" | "move";
+
+function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "message") return entry.message;
+	if (entry.type === "compaction") {
+		return {
+			role: "compactionSummary",
+			summary: entry.summary,
+			tokensBefore: entry.tokensBefore,
+			timestamp: new Date(entry.timestamp).getTime(),
+		};
+	}
+	return undefined;
+}
+
+/** Messages of the active branch, respecting the last compaction (same rule as Pi's handoff.ts). */
+function branchMessages(branch: SessionEntry[]): AgentMessage[] {
+	let c = -1;
+	for (let i = branch.length - 1; i >= 0; i--) {
+		if (branch[i].type === "compaction") {
+			c = i;
+			break;
+		}
+	}
+	if (c < 0) return branch.map(entryToMessage).filter((m) => m !== undefined);
+	const comp = branch[c];
+	const firstKept = comp.type === "compaction" ? branch.findIndex((e) => e.id === comp.firstKeptEntryId) : -1;
+	const kept = [comp, ...(firstKept >= 0 ? branch.slice(firstKept, c) : []), ...branch.slice(c + 1)];
+	return kept.map(entryToMessage).filter((m) => m !== undefined);
+}
+
+export default function rethread(pi: ExtensionAPI) {
+	pi.registerFlag("ledger-file", { type: "string", description: "Ledger file (default .pi/ledger.md)" });
+	pi.registerFlag("rethread-auto-percent", {
+		type: "string",
+		description: "Start /rethread at this context % (default 70; 0 = off)",
+	});
+
+	// Per-session state. Pi runs this factory again for each new session, so it starts fresh there.
+	let phase: Phase = "idle";
+	let goal = "";
+	let review = false;
+	let saved: Omit<Handoff, "goal" | "source"> | undefined;
+	let autoFired = false;
+	let autoDisabled = false;
+	let kickoffRun = false;
+	let pendingAuto = false;
+
+	const threshold = () => parseThreshold(pi.getFlag("rethread-auto-percent"));
+	const ledgerFile = (cwd: string) => resolveLedgerPath(cwd, pi.getFlag("ledger-file"));
+	const previousLedger = (cwd: string) => {
+		const last = readEntries(ledgerFile(cwd)).at(-1);
+		return last ? entryLedger(last) : "";
+	};
+
+	const setTool = (on: boolean) => {
+		const active = pi.getActiveTools().filter((t) => t !== TOOL_NAME);
+		pi.setActiveTools(on ? [...active, TOOL_NAME] : active);
+	};
+
+	const reset = () => {
+		phase = "idle";
+		goal = "";
+		review = false;
+		saved = undefined;
+		setTool(false);
+	};
+
+	const send = (ctx: ExtensionContext, text: string) => {
+		if (ctx.isIdle()) pi.sendUserMessage(text);
+		else pi.sendUserMessage(text, { deliverAs: "followUp" });
+	};
+
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: "Rethread: save handoff",
+		description:
+			"Save the handoff for the next session: a letter to the next agent, then the ledger entry. Only call this when a [rethread] message asks you to.",
+		parameters: Type.Object({
+			status: StringEnum(STATUSES, { description: "landed | partial | blocked" }),
+			next_message: Type.String({ description: "Letter to the next session's agent. Written first." }),
+			ledger: Type.String({ description: "Self-contained ledger entry with the required headings." }),
+		}),
+		defaultActive: false,
+		async execute(_id, params) {
+			if (phase !== "write") {
+				return {
+					content: [{ type: "text", text: "No rethread is in progress; nothing was saved." }],
+					details: { saved: false },
+				};
+			}
+			const problems: string[] = [];
+			if (!params.next_message.trim()) problems.push("next_message is empty");
+			if (!looksLikeLedger(params.ledger)) problems.push("ledger is missing the required ### headings");
+			if (problems.length) {
+				return {
+					content: [{ type: "text", text: `Not saved: ${problems.join("; ")}. Call ${TOOL_NAME} again.` }],
+					details: { saved: false },
+				};
+			}
+			saved = { status: params.status as Status, letter: params.next_message, ledger: params.ledger };
+			return {
+				content: [{ type: "text", text: "Saved. Stop now: the next session starts when you finish." }],
+				details: { saved: true },
+			};
+		},
+	});
+
+	/** Side model call: letter + ledger from the transcript (used by --now and as a fallback). */
+	async function summarize(ctx: ExtensionCommandContext): Promise<{ letter: string; ledger: string } | null> {
+		const messages = branchMessages(ctx.sessionManager.getBranch());
+		if (messages.length === 0 || !ctx.model) return null;
+		const prompt = [
+			"## Previous ledger entry",
+			previousLedger(ctx.cwd) || "(none)",
+			"",
+			"## Conversation",
+			serializeConversation(convertToLlm(messages)),
+			"",
+			"## User's goal for the next session",
+			goal || "(none given: continue the work)",
+		].join("\n");
+		const system = fill(loadTemplate("summary", ctx.cwd), { headings: headingsList() });
+		const run = async (signal?: AbortSignal) => {
+			const user: Message = { role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() };
+			const res = await ctx.modelRegistry.complete(
+				ctx.model!,
+				{ systemPrompt: system, messages: [user] },
+				{ signal, cacheRetention: "none", sessionId: uuidv7() },
+			);
+			if (res.stopReason === "aborted" || res.stopReason === "error") return null;
+			const text = res.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n")
+				.trim();
+			return text ? splitSummary(text) : null;
+		};
+		if (ctx.mode !== "tui") return run(ctx.signal);
+		return ctx.ui.custom((tui, theme, _kb, done) => {
+			const loader = new BorderedLoader(tui, theme, "Writing the handoff...");
+			loader.onAbort = () => done(null);
+			run(loader.signal)
+				.then(done)
+				.catch((err) => {
+					console.error("rethread: summary failed:", err);
+					done(null);
+				});
+			return loader;
+		});
+	}
+
+	/** Step 3: append the ledger, open the new session, send the kickoff. Command context only. */
+	async function move(ctx: ExtensionCommandContext): Promise<void> {
+		phase = "move";
+		setTool(false);
+		let h: Handoff | undefined;
+		if (saved) h = { ...saved, goal, source: "agent" };
+		else {
+			ctx.ui.notify("rethread: the agent did not save a handoff; writing a summary instead", "warning");
+			const s = await summarize(ctx);
+			if (s) h = { ...s, goal, status: "partial", source: "summary" };
+		}
+		if (!h) {
+			ctx.ui.notify("rethread: no handoff could be written; staying in this session", "error");
+			reset();
+			return;
+		}
+		if (review && ctx.mode === "tui") {
+			const edited = await ctx.ui.editor("Edit the ledger entry", h.ledger);
+			if (edited === undefined) {
+				ctx.ui.notify("rethread: cancelled; nothing written", "info");
+				reset();
+				return;
+			}
+			h.ledger = edited;
+		}
+
+		const file = ledgerFile(ctx.cwd);
+		const oldSession = ctx.sessionManager.getSessionFile();
+		const n = appendEntry(file, oldSession, h);
+		const kickoff = fill(loadTemplate("kickoff", ctx.cwd), {
+			ledger_path: shownPath(file, ctx.cwd),
+			letter: h.letter.trim() || "(none)",
+			goal_line: goalLine(h.goal, false),
+			status: h.status,
+			ledger: h.ledger.trim(),
+		});
+		reset();
+
+		// Only plain data crosses the switch; ctx is stale afterwards.
+		const result = await ctx.newSession({
+			parentSession: oldSession,
+			withSession: async (next) => {
+				next.ui.notify(`Ledger entry ${n} written; new session started`, "info");
+				// Not awaited: the run would hold the switch open until it ends.
+				next.sendUserMessage(kickoff).catch((err) => console.error("rethread: kickoff failed:", err));
+			},
+		});
+		if (result.cancelled) ctx.ui.notify(`Ledger entry ${n} written, but the new session was cancelled`, "warning");
+	}
+
+	pi.registerCommand("rethread", {
+		description: "Finish, write a letter and a ledger entry, continue in a new session",
+		handler: async (raw, ctx) => {
+			const a = parseArgs(raw);
+			if (a.cancel) {
+				if (phase === "idle") ctx.ui.notify("rethread: nothing to cancel", "info");
+				else {
+					reset();
+					ctx.ui.notify("rethread: cancelled", "info");
+				}
+				return;
+			}
+			if (a.switchNow) {
+				if (phase === "write") await move(ctx);
+				return;
+			}
+			if (phase !== "idle") {
+				ctx.ui.notify(`rethread: already in progress (${phase}); /rethread --cancel to stop`, "warning");
+				return;
+			}
+			if (!ctx.model) {
+				ctx.ui.notify("rethread: no model selected", "error");
+				return;
+			}
+			if (branchMessages(ctx.sessionManager.getBranch()).length === 0) {
+				ctx.ui.notify(`rethread: nothing to carry over yet. ${USAGE}`, "warning");
+				return;
+			}
+			goal = a.goal;
+			review = a.review;
+			if (a.now) {
+				await ctx.waitForIdle();
+				phase = "write"; // so move() accepts it; saved stays empty -> summary path
+				await move(ctx);
+				return;
+			}
+			phase = "land";
+			ctx.ui.notify("rethread 1/3: asking the agent to finish its step", "info");
+			send(ctx, loadTemplate("land", ctx.cwd).trim());
+		},
+	});
+
+	pi.registerCommand("ledger", {
+		description: "Show the ledger file and its number of entries",
+		handler: async (_args, ctx) => {
+			const file = ledgerFile(ctx.cwd);
+			const n = readEntries(file).length;
+			ctx.ui.notify(n ? `Ledger: ${file} (${n} entries)` : `No ledger yet (${file})`, "info");
+		},
+	});
+
+	pi.on("session_start", async () => {
+		phase = "idle";
+		saved = undefined;
+		autoFired = false;
+		autoDisabled = false;
+		kickoffRun = false;
+		pendingAuto = false;
+	});
+
+	// Pi's automatic compaction becomes a rethread: at the threshold, and after a reply that
+	// silently went past the window (reason "overflow", nothing to retry). Left alone: manual
+	// /compact, and recovery of a request the provider rejected as too long (willRetry), which
+	// must compact to retry the failed turn.
+	pi.on("session_before_compact", async (event) => {
+		if (event.reason === "manual" || event.willRetry) return;
+		if (phase !== "idle") return { cancel: true }; // we are leaving this session anyway
+		if (threshold() <= 0 || autoDisabled || autoFired) return;
+		pendingAuto = true;
+		return { cancel: true };
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (event.messageType === "user" && isKickoff(event.prompt)) kickoffRun = true;
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		// Advance a rethread in progress. Prompts sent here are deferred by Pi until settling ends.
+		if (phase === "land") {
+			phase = "write";
+			setTool(true);
+			ctx.ui.notify("rethread 2/3: asking for the letter and the ledger", "info");
+			pi.sendUserMessage(
+				fill(loadTemplate("write", ctx.cwd), {
+					tool: TOOL_NAME,
+					headings: headingsList(),
+					goal_line: goalLine(goal, true),
+					previous: previousLedger(ctx.cwd) || "(none)",
+				}),
+			);
+			return;
+		}
+		if (phase === "write") {
+			ctx.ui.notify("rethread 3/3: moving to a new session", "info");
+			pi.sendUserMessage("/rethread --switch", { expandPromptTemplates: true });
+			return;
+		}
+		if (phase !== "idle") return;
+
+		const limit = threshold();
+		const pct = ctx.getContextUsage()?.percent;
+		if (kickoffRun) {
+			kickoffRun = false;
+			// Loop guard: a new session already over the limit would rethread forever.
+			if (pendingAuto || (limit > 0 && pct != null && pct >= limit)) {
+				pendingAuto = false;
+				autoDisabled = true;
+				ctx.ui.notify(
+					`rethread: context is already ${pct != null ? `${Math.round(pct)}%` : "at Pi's compaction point"} right after the handoff; automatic rethread is off for this session. Raise --rethread-auto-percent or shorten the ledger.`,
+					"warning",
+				);
+			}
+			return;
+		}
+		if (limit <= 0 || autoFired || autoDisabled) return;
+		if (!pendingAuto && (pct == null || pct < limit)) return;
+		autoFired = true;
+		ctx.ui.notify(
+			pendingAuto
+				? "rethread: Pi would compact now; rethreading instead"
+				: `rethread: context at ${Math.round(pct!)}%; rethreading`,
+			"info",
+		);
+		pendingAuto = false;
+		pi.sendUserMessage("/rethread", { expandPromptTemplates: true });
+	});
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@machine-made/pi-rethread",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "author": "Ricardo Frantz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/machine-made/pi-rethread.git"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typebox": "1.3.27",
+    "typescript": "^5.9.0"
+  },
+  "bugs": {
+    "url": "https://github.com/machine-made/pi-rethread/issues"
+  },
+  "description": "Pi extension: the agent finishes its step, writes a letter and a ledger entry, and the work continues in a fresh session",
+  "files": [
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "index.ts",
+    "rethread.ts",
+    "prompts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/machine-made/pi-rethread#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "llm",
+    "developer-tools",
+    "context",
+    "handoff",
+    "ledger",
+    "session"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts"
+  },
+  "type": "module",
+  "packageManager": "bun@1.3.13"
+}

package/prompts/kickoff.md

@@ -0,0 +1,12 @@
+This session continues earlier work. The ledger is `{{ledger_path}}` (newest entry last); its latest entry is below.
+
+Letter from the previous session's agent:
+{{letter}}
+
+{{goal_line}}
+
+First, reply with a 3-line readback: (1) the goal, (2) your first action, (3) the main risk. Then start. Check the files the ledger names before you change them.
+
+<rethread-ledger status="{{status}}">
+{{ledger}}
+</rethread-ledger>

package/prompts/land.md

@@ -0,0 +1,9 @@
+[rethread 1/2: land] This session is about to end and a fresh session will continue the work.
+
+Land the work now:
+- Finish the step you are on if it needs only a few more actions. Do not start anything new.
+- Leave no half-edited file. If a change cannot be finished, revert it or leave a clear `TODO(rethread)` comment.
+- If the project has a quick check (tests, build, lint), run it once.
+- Then reply in at most 3 lines: what is **verified** (you ran or saw it), what is **assumed** (not checked), and anything still broken.
+
+Do not write the handoff yet; that is the next step.

package/prompts/summary.md

@@ -0,0 +1,11 @@
+You write a handoff so a fresh coding-agent session can continue the work with no access to the old conversation. You get the previous ledger entry (may be empty), the conversation since then, and optionally the user's goal for the next session.
+
+Output exactly two sections and nothing else.
+
+## Letter
+A short message to the next agent ("You..."): **Where we are** (two sentences), **Do first** (one action), **Watch out**, **Don't redo** (failed approaches and why), **Trust** (verified vs assumed).
+
+## Ledger
+Self-contained durable facts with exactly these headings, in this order ("none" under an empty heading):
+{{headings}}
+Carry over what is still true from the previous entry; drop what is obsolete. Be specific: exact paths, commands, numbers, error messages.

package/prompts/write.md

@@ -0,0 +1,21 @@
+[rethread 2/2: write] Now write the handoff with one call to the `{{tool}}` tool. Fill the fields in this order.
+
+**`next_message`**: a letter from you to the agent of the next session. Write it to them ("You..."), short, in this shape:
+- **Where we are**: two sentences.
+- **Do first**: one concrete action.
+- **Watch out**: traps, flaky tests, things that look right but are not.
+- **Don't redo**: approaches already tried that failed, and why.
+- **Trust**: what is verified and what is only assumed.
+
+**`ledger`**: durable facts that stay true across many sessions. Self-contained: the next agent has no access to this conversation. Use exactly these headings, in this order, and write "none" under a heading with nothing to say:
+{{headings}}
+Carry over what is still true from the previous entry; drop what is finished or obsolete. Be specific: exact paths, commands, numbers, error messages.
+
+**`status`**: `landed` (clean stopping point), `partial` (work in progress, described in the ledger) or `blocked` (cannot continue without the user).
+
+{{goal_line}}
+
+Previous ledger entry:
+{{previous}}
+
+After the tool call, stop.

package/rethread.ts

@@ -0,0 +1,143 @@
+// Pure helpers for pi-rethread: templates, ledger file, kickoff. No Pi runtime imports.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const ENTRY_MARK = "<!-- ledger-entry -->";
+export const DEFAULT_LEDGER = ".pi/ledger.md";
+export const DEFAULT_AUTO_PERCENT = 70;
+export const TOOL_NAME = "rethread_save";
+export const KICKOFF_TAG = "rethread-ledger";
+export const OVERRIDE_DIR = ".pi/rethread";
+export const USAGE = "Usage: /rethread [goal for the next session] [--now] [--review] [--cancel]";
+
+export const LEDGER_HEADINGS = ["Goal", "Done", "Decisions", "Files", "Commands", "Open problems", "Next steps"] as const;
+export const STATUSES = ["landed", "partial", "blocked"] as const;
+export type Status = (typeof STATUSES)[number];
+
+export type TemplateName = "land" | "write" | "kickoff" | "summary";
+
+const PACKAGE_PROMPTS = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+
+/** Project override in .pi/rethread/<name>.md wins over the packaged template. */
+export function loadTemplate(name: TemplateName, cwd: string): string {
+	const own = join(cwd, OVERRIDE_DIR, `${name}.md`);
+	return readFileSync(existsSync(own) ? own : join(PACKAGE_PROMPTS, `${name}.md`), "utf8");
+}
+
+/** Replace {{key}} placeholders; unknown keys are left as they are. */
+export function fill(template: string, vars: Record<string, string>): string {
+	return template.replace(/\{\{(\w+)\}\}/g, (m, k: string) => (k in vars ? vars[k] : m)).trim();
+}
+
+export const headingsList = (): string => LEDGER_HEADINGS.map((h) => `### ${h}`).join("\n");
+
+export function goalLine(goal: string, forNextSession: boolean): string {
+	if (goal) return `The user's goal for ${forNextSession ? "the next" : "this"} session: ${goal}`;
+	return forNextSession
+		? "The user gave no goal: the next session continues the work."
+		: 'Continue with the first item under "Next steps".';
+}
+
+export interface Args {
+	goal: string;
+	now: boolean;
+	review: boolean;
+	cancel: boolean;
+	switchNow: boolean;
+}
+
+export function parseArgs(raw: string): Args {
+	const words = raw.trim().split(/\s+/).filter(Boolean);
+	const flags = new Set(words.filter((w) => w.startsWith("--")));
+	return {
+		goal: words.filter((w) => !w.startsWith("--")).join(" "),
+		now: flags.has("--now"),
+		review: flags.has("--review"),
+		cancel: flags.has("--cancel"),
+		switchNow: flags.has("--switch"), // internal: sent by the extension itself
+	};
+}
+
+export function resolveLedgerPath(cwd: string, flag: unknown): string {
+	const p = typeof flag === "string" && flag.trim() ? flag.trim() : DEFAULT_LEDGER;
+	return isAbsolute(p) ? p : join(cwd, p);
+}
+
+/** Context percent that starts an automatic rethread; 0 means off. */
+export function parseThreshold(flag: unknown): number {
+	if (typeof flag !== "string" || flag.trim() === "") return DEFAULT_AUTO_PERCENT;
+	const n = Number(flag);
+	return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+export function readEntries(file: string): string[] {
+	if (!existsSync(file)) return [];
+	return readFileSync(file, "utf8")
+		.split(ENTRY_MARK)
+		.slice(1)
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+export interface Handoff {
+	goal: string;
+	letter: string;
+	ledger: string;
+	status: Status;
+	source: "agent" | "summary";
+}
+
+/** Append one entry atomically (temp file, then rename). Returns the entry number. */
+export function appendEntry(file: string, sessionFile: string | undefined, h: Handoff, now = new Date()): number {
+	mkdirSync(dirname(file), { recursive: true });
+	const header = existsSync(file)
+		? readFileSync(file, "utf8")
+		: "# Ledger\n\nWritten by /rethread (pi-rethread). Newest entry last. Each entry is self-contained.\n";
+	const n = readEntries(file).length + 1;
+	const meta = [
+		`## Entry ${n} — ${now.toISOString()}`,
+		"",
+		`- From session: \`${sessionFile ? basename(sessionFile) : "in-memory"}\``,
+		`- Status: ${h.status} (written by ${h.source === "agent" ? "the agent" : "a summary"})`,
+		h.goal ? `- Goal for next session: ${h.goal.replace(/\s+/g, " ").trim()}` : undefined,
+	]
+		.filter((l) => l !== undefined)
+		.join("\n");
+	const letter = h.letter.trim() ? `\n\n### Letter to the next session\n${h.letter.trim()}` : "";
+	const text = `${header.trimEnd()}\n\n${ENTRY_MARK}\n${meta}\n\n${h.ledger.trim()}${letter}\n`;
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, text, "utf8");
+	renameSync(tmp, file);
+	return n;
+}
+
+/** The ledger part of a stored entry (no metadata, no letter): what the next write builds on. */
+export function entryLedger(entry: string): string {
+	return entry
+		.replace(/^## Entry \d+ — .*$/m, "")
+		.replace(/^- (From session|Status|Goal for next session):.*$/gm, "")
+		.split(/^### Letter to the next session$/m)[0]
+		.trim();
+}
+
+/** Split the fallback summary ("## Letter" / "## Ledger") into its parts. */
+export function splitSummary(text: string): { letter: string; ledger: string } {
+	const m = text.match(/^##\s*Letter\s*$([\s\S]*?)^##\s*Ledger\s*$([\s\S]*)/im);
+	if (!m) return { letter: "", ledger: text.trim() };
+	return { letter: m[1].trim(), ledger: m[2].trim() };
+}
+
+export function isKickoff(prompt: string): boolean {
+	return prompt.includes(`<${KICKOFF_TAG}`);
+}
+
+/** A usable ledger has most of the expected headings. */
+export function looksLikeLedger(text: string): boolean {
+	return LEDGER_HEADINGS.filter((h) => new RegExp(`^#{2,4}\\s*${h}\\b`, "mi").test(text)).length >= 4;
+}
+
+export function shownPath(file: string, cwd: string): string {
+	const r = relative(cwd, file);
+	return r && !r.startsWith("..") ? r : file;
+}