@phi-code-admin/phi-code 0.83.0 → 0.84.0

package/extensions/phi/todo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/phi/todo/config.ts

@@ -0,0 +1,14 @@
+import type { GuidanceFields } from "./rpiv-config/index.js";
+import { configPath, loadJsonConfig, validateGuidanceFields } from "./rpiv-config/index.js";
+
+const CONFIG_PATH = configPath("rpiv-todo");
+
+interface TodoConfig {
+	guidance?: GuidanceFields;
+}
+
+export function loadConfig(): TodoConfig {
+	return loadJsonConfig<TodoConfig>(CONFIG_PATH);
+}
+
+export { validateGuidanceFields };

package/extensions/phi/todo/index.ts

@@ -0,0 +1,113 @@
+/**
+ * rpiv-todo — Pi extension. Registers the `todo` tool, `/todos` slash
+ * command, and the persistent TodoOverlay widget.
+ *
+ * TUI chrome strings localize at render time via the i18n bridge. Strings are
+ * registered with rpiv-i18n here, once, at module init — but only when the
+ * SDK is actually installed. If `@juicesharp/rpiv-i18n` is missing (standalone
+ * install of just this package), the dynamic-load shim no-ops and the bridge's
+ * `t(key, fallback)` returns the inline English literal at every call site.
+ * The extension stays online either way.
+ *
+ * Adding a locale: drop `locales/<code>.json` next to en.json (mirroring the
+ * key set). No edit needed here — `registerLocalesFromDir` iterates
+ * `SUPPORTED_LOCALES` from the SDK. See `@juicesharp/rpiv-i18n` README →
+ * "Contributing translations" for the full convention.
+ *
+ * Extracted from rpiv-pi@7525a5d. Tool name "todo" and widget key
+ * "rpiv-todos" preserved verbatim so existing session history replays
+ * correctly after upgrade.
+ */
+
+import type { ExtensionAPI } from "phi-code";
+import { I18N_NAMESPACE } from "./state/i18n-bridge.js";
+import { replayFromBranch } from "./state/replay.js";
+import { replaceState } from "./state/store.js";
+import { registerTodosCommand, registerTodoTool, TOOL_NAME } from "./todo.js";
+import { TodoOverlay } from "./todo-overlay.js";
+
+type I18nLoader = {
+	registerLocalesFromDir: (namespace: string, packageUrl: string, options?: { label?: string }) => void;
+};
+
+// Dynamic import keeps `@juicesharp/rpiv-i18n` a soft optional peer: when the
+// SDK is installed alongside this package the strings register and
+// `/languages` flips them live; when it isn't, the import rejects here, we
+// no-op, and the bridge's English-fallback shim keeps the extension online.
+//
+// The `/loader` subpath is used instead of the SDK entry so the i18n-ui +
+// pi-tui modules are not pulled into our load graph just to register strings.
+try {
+	const i18nLoaderSpecifier: string = "@juicesharp/rpiv-i18n/loader";
+	const sdk = (await import(i18nLoaderSpecifier)) as I18nLoader;
+	sdk.registerLocalesFromDir(I18N_NAMESPACE, import.meta.url, { label: "rpiv-todo" });
+} catch {
+	// SDK absent — extension still loads with English-only UI.
+}
+
+// pi-core's ExtensionRunner throws this exact phrase from an invalidated ctx
+// proxy after session replacement/reload. Match the stable substring so genuine
+// replay bugs still propagate instead of being silently swallowed.
+function isStaleCtxError(e: unknown): boolean {
+	return /stale after session replacement/.test(String(e));
+}
+
+export default function (pi: ExtensionAPI) {
+	// Todo overlay widget — constructed lazily at the first session_start with UI.
+	let todoOverlay: TodoOverlay | undefined;
+
+	registerTodoTool(pi);
+	registerTodosCommand(pi);
+
+	pi.on("session_start", async (_event, ctx) => {
+		replaceState(replayFromBranch(ctx));
+		if (ctx.hasUI) {
+			todoOverlay ??= new TodoOverlay();
+			todoOverlay.setUICtx(ctx.ui);
+			todoOverlay.resetCompletedDisplayState();
+			todoOverlay.update();
+		}
+	});
+
+	pi.on("session_compact", async (_event, ctx) => {
+		// Auto-compaction races session disposal: pi-core invalidates the
+		// extension runner while still emitting session_compact, so `ctx` may be
+		// a dead proxy whose getters throw the stale error. The compacting session
+		// is being discarded — the replacement session's session_start replays
+		// state — so keep current state on a stale ctx. Other errors are real
+		// replay bugs and must propagate.
+		try {
+			replaceState(replayFromBranch(ctx));
+		} catch (e) {
+			if (!isStaleCtxError(e)) throw e;
+		}
+		todoOverlay?.resetCompletedDisplayState();
+		todoOverlay?.update();
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		try {
+			replaceState(replayFromBranch(ctx));
+		} catch (e) {
+			if (!isStaleCtxError(e)) throw e;
+		}
+		todoOverlay?.resetCompletedDisplayState();
+		todoOverlay?.update();
+	});
+
+	pi.on("session_shutdown", async () => {
+		todoOverlay?.dispose();
+		todoOverlay = undefined;
+	});
+
+	// Reads getTodos() at render time; do NOT call replayFromBranch here
+	// (branch is stale — message_end runs after tool_execution_end).
+	pi.on("tool_execution_end", async (event) => {
+		if (event.toolName !== TOOL_NAME || event.isError) return;
+		todoOverlay?.update();
+	});
+
+	pi.on("agent_start", async () => {
+		todoOverlay?.hideCompletedTasksFromPreviousTurn();
+	});
+}

package/extensions/phi/todo/locales/de.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated. Note: 'overlay.more' renders as '+5 weitere' which is grammatically loose for plural agreement — accepted for badge brevity.",
+
+  "status.pending": "ausstehend",
+  "status.in_progress": "in Bearbeitung",
+  "status.completed": "erledigt",
+  "status.deleted": "gelöscht",
+
+  "overlay.heading": "Todos",
+  "overlay.more": "weitere",
+
+  "command.no_todos": "Noch keine Todos. Bitte den Agenten, welche hinzuzufügen!",
+  "command.requires_interactive": "/todos erfordert den interaktiven Modus",
+  "command.section.pending": "── Ausstehend ──",
+  "command.section.in_progress": "── In Bearbeitung ──",
+  "command.section.completed": "── Erledigt ──"
+}

package/extensions/phi/todo/locales/en.json

@@ -0,0 +1,15 @@
+{
+  "status.pending": "pending",
+  "status.in_progress": "in progress",
+  "status.completed": "completed",
+  "status.deleted": "deleted",
+
+  "overlay.heading": "Todos",
+  "overlay.more": "more",
+
+  "command.no_todos": "No todos yet. Ask the agent to add some!",
+  "command.requires_interactive": "/todos requires interactive mode",
+  "command.section.pending": "── Pending ──",
+  "command.section.in_progress": "── In Progress ──",
+  "command.section.completed": "── Completed ──"
+}

package/extensions/phi/todo/locales/es.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendientes",
+  "status.in_progress": "en curso",
+  "status.completed": "completadas",
+  "status.deleted": "eliminada",
+
+  "overlay.heading": "Tareas",
+  "overlay.more": "más",
+
+  "command.no_todos": "Sin tareas aún. ¡Pídele al agente que añada algunas!",
+  "command.requires_interactive": "/todos requiere modo interactivo",
+  "command.section.pending": "── Pendientes ──",
+  "command.section.in_progress": "── En curso ──",
+  "command.section.completed": "── Completadas ──"
+}

package/extensions/phi/todo/locales/fr.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "en attente",
+  "status.in_progress": "en cours",
+  "status.completed": "terminées",
+  "status.deleted": "supprimée",
+
+  "overlay.heading": "Tâches",
+  "overlay.more": "autres",
+
+  "command.no_todos": "Pas encore de tâches. Demandez à l'agent d'en ajouter !",
+  "command.requires_interactive": "/todos nécessite le mode interactif",
+  "command.section.pending": "── En attente ──",
+  "command.section.in_progress": "── En cours ──",
+  "command.section.completed": "── Terminées ──"
+}

package/extensions/phi/todo/locales/pt-BR.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendentes",
+  "status.in_progress": "em andamento",
+  "status.completed": "concluídas",
+  "status.deleted": "excluída",
+
+  "overlay.heading": "Tarefas",
+  "overlay.more": "mais",
+
+  "command.no_todos": "Nenhuma tarefa ainda. Peça ao agente para adicionar algumas!",
+  "command.requires_interactive": "/todos requer modo interativo",
+  "command.section.pending": "── Pendentes ──",
+  "command.section.in_progress": "── Em andamento ──",
+  "command.section.completed": "── Concluídas ──"
+}

package/extensions/phi/todo/locales/pt.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendentes",
+  "status.in_progress": "em curso",
+  "status.completed": "concluídas",
+  "status.deleted": "eliminada",
+
+  "overlay.heading": "Tarefas",
+  "overlay.more": "mais",
+
+  "command.no_todos": "Sem tarefas ainda. Peça ao agente para adicionar algumas!",
+  "command.requires_interactive": "/todos requer modo interativo",
+  "command.section.pending": "── Pendentes ──",
+  "command.section.in_progress": "── Em curso ──",
+  "command.section.completed": "── Concluídas ──"
+}

package/extensions/phi/todo/locales/ru.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Автоперевод. Приветствуется проверка носителем языка через PR. Символы юникода (──) не переводятся.",
+
+  "status.pending": "ожидание",
+  "status.in_progress": "в работе",
+  "status.completed": "выполнено",
+  "status.deleted": "удалена",
+
+  "overlay.heading": "Задачи",
+  "overlay.more": "ещё",
+
+  "command.no_todos": "Задач пока нет. Попросите агента добавить!",
+  "command.requires_interactive": "/todos требует интерактивного режима",
+  "command.section.pending": "── Ожидание ──",
+  "command.section.in_progress": "── В работе ──",
+  "command.section.completed": "── Выполнено ──"
+}

package/extensions/phi/todo/locales/uk.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Автопереклад. Привітна перевірка носієм мови через PR. Символи юнікоду (──) не перекладаються.",
+
+  "status.pending": "очікування",
+  "status.in_progress": "у роботі",
+  "status.completed": "виконано",
+  "status.deleted": "видалено",
+
+  "overlay.heading": "Завдання",
+  "overlay.more": "ще",
+
+  "command.no_todos": "Завдань поки немає. Попросіть агента додати!",
+  "command.requires_interactive": "/todos потребує інтерактивного режиму",
+  "command.section.pending": "── Очікування ──",
+  "command.section.in_progress": "── У роботі ──",
+  "command.section.completed": "── Виконано ──"
+}

package/extensions/phi/todo/rpiv-config/config.ts

@@ -0,0 +1,223 @@
+/**
+ * rpiv-config — shared config I/O utilities for rpiv-mono sibling packages.
+ *
+ * Provides JSON config load/save with crash-resistant defaults, path resolution,
+ * guidance-field validation, env-var fallback, and TypeBox-driven schema validation.
+ * Stateless — no module-level singletons, no globalThis caches, no side effects.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { type Static, type TObject, Type } from "typebox";
+import { Value } from "typebox/value";
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a config file path under `~/.config/<name>/`.
+ *
+ * @param name — package directory name (e.g. "rpiv-todo")
+ * @param file — config filename (defaults to "config.json")
+ * @returns absolute path to the config file
+ */
+export function configPath(name: string, file: string = "config.json"): string {
+	return join(homedir(), ".config", name, file);
+}
+
+// ---------------------------------------------------------------------------
+// JSON config load — Variant A (with typeof guard) universally
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and parse a JSON config file.
+ *
+ * Returns `{}` for missing files, malformed JSON, or non-plain-object values.
+ * The typeof guard fixes a latent bug where valid non-object JSON
+ * (e.g. `"hello"`, `42`, `null`) passes through the cast. Arrays are also
+ * rejected — `typeof [] === "object"` in JavaScript, but config files are
+ * always plain objects.
+ */
+export function loadJsonConfig<T>(path: string): T {
+	if (!existsSync(path)) return {} as T;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {} as T;
+		return parsed as T;
+	} catch (err) {
+		// Diagnostic for malformed-JSON path. Silent save + silent load otherwise
+		// produce identical user-visible symptoms (state reverts on next start)
+		// with zero diagnostic surface — the user cannot tell "never saved" from
+		// "saved-but-unreadable." Warning is owner-only since the file lives in
+		// the user's HOME.
+		console.warn(`rpiv-config: invalid JSON at ${path}, using default ({}) — ${(err as Error).message}`);
+		return {} as T;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// JSON config save — best-effort void
+// ---------------------------------------------------------------------------
+
+/** File mode for config files (user read/write only). */
+const CONFIG_FILE_MODE = 0o600;
+
+/**
+ * Persist a config object as formatted JSON. Returns `true` on successful
+ * mkdir+write, `false` on filesystem failure (disk full, EACCES, EROFS, …).
+ *
+ * Every current rpiv-* save call site is user-initiated and shows a
+ * "Saved …" notification — callers MUST guard the success notification on
+ * the boolean return so a silent disk failure can't make the success message
+ * lie on disk-full / EACCES.
+ *
+ * The chmod step is best-effort and never affects the return value: some
+ * filesystems (tmpfs, network mounts, Windows-style perms) silently ignore
+ * chmod and there is no portable way to enforce 0600 perms across platforms.
+ * Callers that genuinely don't care about persistence outcome can discard
+ * the return — TypeScript does not warn on ignored `boolean`.
+ */
+export function saveJsonConfig(path: string, data: unknown): boolean {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+	} catch {
+		return false;
+	}
+	try {
+		chmodSync(path, CONFIG_FILE_MODE);
+	} catch {
+		// chmod may fail on some filesystems — best effort only, never gates success
+	}
+	return true;
+}
+
+// ---------------------------------------------------------------------------
+// GuidanceFields — extracted from 4 byte-identical copies
+// ---------------------------------------------------------------------------
+
+export interface GuidanceFields {
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+}
+
+// TypeBox form of GuidanceFields. Mirrors the interface 1:1 — same fields,
+// same optionality. `additionalProperties: true` lets consumers compose
+// wrappers that may carry sibling-specific keys without those leaking back
+// into rpiv-config. The runtime invariants (non-empty string, non-empty
+// array of non-empty strings) are still enforced by `validateGuidanceFields`;
+// the schema is a structural type-narrowing aid for callers that bake
+// guidance into a larger TypeBox-validated config object.
+export const GuidanceFieldsSchema = Type.Object(
+	{
+		promptSnippet: Type.Optional(Type.String()),
+		promptGuidelines: Type.Optional(Type.Array(Type.String())),
+	},
+	{ additionalProperties: true },
+);
+
+/**
+ * Validate and extract guidance fields from an unknown value.
+ *
+ * Returns a clean `GuidanceFields` object with only valid entries.
+ * Byte-identical logic previously in rpiv-todo, rpiv-ask-user-question,
+ * rpiv-advisor, and rpiv-web-tools.
+ */
+export function validateGuidanceFields(fields: unknown): GuidanceFields {
+	if (!fields || typeof fields !== "object") return {};
+	const g = fields as Record<string, unknown>;
+	const result: GuidanceFields = {};
+	if (typeof g.promptSnippet === "string" && g.promptSnippet.length > 0) {
+		result.promptSnippet = g.promptSnippet;
+	}
+	if (
+		Array.isArray(g.promptGuidelines) &&
+		g.promptGuidelines.length > 0 &&
+		g.promptGuidelines.every((s) => typeof s === "string" && s.length > 0)
+	) {
+		result.promptGuidelines = g.promptGuidelines;
+	}
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Model key codec — provider:id string ↔ { provider, modelId } object.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a model key string into its components.
+ *
+ * Accepts EITHER separator on read:
+ *   - "provider/modelId" — canonical form (emitted by modelKey and persisted
+ *     by post-slash-canonical-migration consumers).
+ *   - "provider:modelId" — legacy form (persisted by released rpiv-advisor
+ *     1.16+ before the migration). Auto-rewritten on the next save by any
+ *     consumer that re-serialises via modelKey.
+ *
+ * Slash is preferred when present — a key like "provider:foo/bar" splits on
+ * `/`, so the modelId is "bar" rather than re-introducing the legacy
+ * interpretation. No current model id contains a `/` so this asymmetry has
+ * no real-world ambiguity.
+ */
+export function parseModelKey(key: string): { provider: string; modelId: string } | undefined {
+	const slashIdx = key.indexOf("/");
+	if (slashIdx >= 1) return { provider: key.slice(0, slashIdx), modelId: key.slice(slashIdx + 1) };
+	const colonIdx = key.indexOf(":");
+	if (colonIdx >= 1) return { provider: key.slice(0, colonIdx), modelId: key.slice(colonIdx + 1) };
+	return undefined;
+}
+
+/**
+ * Compose the canonical "provider/modelId" string from provider and modelId
+ * components. Slash-only emission; paired with parseModelKey's tolerant read,
+ * legacy colon-form persisted values auto-migrate the next time any consumer
+ * re-serialises through this codec.
+ */
+export function modelKey(m: { provider: string; id: string }): string {
+	return `${m.provider}/${m.id}`;
+}
+
+// ---------------------------------------------------------------------------
+// Env-var fallback
+// ---------------------------------------------------------------------------
+
+/**
+ * Read an environment variable with optional fallback.
+ *
+ * Trims whitespace from the env value. Returns `fallback` (or `undefined`)
+ * when the variable is unset or empty after trimming.
+ */
+export function readEnvVar(key: string, fallback?: string): string | undefined {
+	return process.env[key]?.trim() || fallback;
+}
+
+// ---------------------------------------------------------------------------
+// TypeBox-driven schema validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and clean a config value against a TypeBox schema.
+ *
+ * 1. Guards against non-plain-object input (returns `{}` for primitives, arrays).
+ * 2. Clones the input (Value.Clean mutates).
+ * 3. Strips unknown properties via `Value.Clean`.
+ * 4. Applies schema defaults via `Value.Create` (spread merge: defaults
+ *    provide base, cleaned value overrides).
+ * 5. Returns the validated, cleaned object typed as the schema's static type.
+ *
+ * Falls back to `{}` on any failure — same fail-soft contract as `loadJsonConfig`.
+ */
+export function validateConfig<T extends TObject>(schema: T, value: unknown): Static<T> {
+	try {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) return {} as Static<T>;
+		const cleaned = Value.Clean(schema, Value.Clone(value));
+		const defaults = Value.Create(schema);
+		// Merge: defaults as base, cleaned values override.
+		// Both are plain objects from TypeBox operations — safe spread via Record cast.
+		return { ...(defaults as Record<string, unknown>), ...(cleaned as Record<string, unknown>) } as Static<T>;
+	} catch {
+		return {} as Static<T>;
+	}
+}

package/extensions/phi/todo/rpiv-config/index.ts

@@ -0,0 +1,12 @@
+export {
+	configPath,
+	type GuidanceFields,
+	GuidanceFieldsSchema,
+	loadJsonConfig,
+	modelKey,
+	parseModelKey,
+	readEnvVar,
+	saveJsonConfig,
+	validateConfig,
+	validateGuidanceFields,
+} from "./config.js";

package/extensions/phi/todo/state/i18n-bridge.ts

@@ -0,0 +1,65 @@
+/**
+ * i18n bridge for rpiv-todo — single thin import surface so every call site
+ * routes through one module. Backed by `@juicesharp/rpiv-i18n`'s SDK when
+ * available; degrades to canonical-English fallbacks when not.
+ *
+ * - `t(key, fallback)` is `scope("@juicesharp/rpiv-todo")` if the SDK is
+ *   installed (live `/languages` updates propagate). If the SDK is missing
+ *   (standalone install without rpiv-i18n), `t` is an identity passthrough
+ *   that returns the inline English fallback at every call site, so the
+ *   extension stays online with English UI.
+ * - `formatStatusLabel(status)` resolves a TaskStatus to its locale-aware
+ *   label via the canonical `status.*` namespace, with the English literal
+ *   as fallback so nothing renders blank if the namespace isn't registered.
+ *   This is the SINGLE point of localization for status words — overlay,
+ *   /todos header, /todos render-call all route through here.
+ *
+ * Strings are registered ONCE at extension load (see ../index.ts). Call sites
+ * MUST use this module at render time — never bake the result into a top-level
+ * `const X = formatStatusLabel(...)`.
+ */
+
+import type { TaskStatus } from "../tool/types.js";
+
+export const I18N_NAMESPACE = "@juicesharp/rpiv-todo";
+
+type ScopeFn = (key: string, fallback: string) => string;
+type I18nSDK = { scope: (namespace: string) => ScopeFn };
+
+// Prefer the live SDK if installed: closures it returns track the active
+// locale, so /languages picker propagates to our render call sites. If the
+// SDK isn't installed (standalone install of this extension without
+// rpiv-i18n), the dynamic import fails, every t(key, fallback) returns the
+// canonical English literal, and the extension stays online.
+//
+// Top-level await is required so a synchronous `t(...)` call from any
+// downstream module sees the resolved scope; ESM module loading awaits this
+// before evaluating any importer.
+let scopeImpl: ScopeFn;
+try {
+	const i18nSpecifier: string = "@juicesharp/rpiv-i18n";
+	const sdk = (await import(i18nSpecifier)) as I18nSDK;
+	scopeImpl = sdk.scope(I18N_NAMESPACE);
+} catch {
+	scopeImpl = (_key, fallback) => fallback;
+}
+
+export const t: ScopeFn = scopeImpl;
+
+const STATUS_LABEL_PENDING = "pending";
+const STATUS_LABEL_IN_PROGRESS = "in progress";
+const STATUS_LABEL_COMPLETED = "completed";
+const STATUS_LABEL_DELETED = "deleted";
+
+export function formatStatusLabel(status: TaskStatus): string {
+	switch (status) {
+		case "pending":
+			return t("status.pending", STATUS_LABEL_PENDING);
+		case "in_progress":
+			return t("status.in_progress", STATUS_LABEL_IN_PROGRESS);
+		case "completed":
+			return t("status.completed", STATUS_LABEL_COMPLETED);
+		case "deleted":
+			return t("status.deleted", STATUS_LABEL_DELETED);
+	}
+}

package/extensions/phi/todo/state/invariants.ts

@@ -0,0 +1,20 @@
+import type { TaskStatus } from "../tool/types.js";
+
+/**
+ * Allowed forward transitions per source status. `completed` is one-way to
+ * `deleted` (never back to `in_progress`); `deleted` is terminal.
+ *
+ * Idempotent same→same is checked separately in `isTransitionValid` so this
+ * table only enumerates actual transitions.
+ */
+export const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+	pending: new Set(["in_progress", "completed", "deleted"]),
+	in_progress: new Set(["pending", "completed", "deleted"]),
+	completed: new Set(["deleted"]),
+	deleted: new Set(),
+};
+
+export function isTransitionValid(from: TaskStatus, to: TaskStatus): boolean {
+	if (from === to) return true;
+	return VALID_TRANSITIONS[from].has(to);
+}

package/extensions/phi/todo/state/replay.ts

@@ -0,0 +1,38 @@
+import type { TaskDetails } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Discriminator for `details` envelopes that match the persisted `TaskDetails`
+ * shape. Defensive — branch entries from older or corrupt sessions are
+ * skipped silently.
+ */
+export function isTaskDetails(value: unknown): value is TaskDetails {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.tasks) && typeof v.nextId === "number";
+}
+
+/**
+ * Walk the current branch in chronological order; the LAST `toolResult` whose
+ * `toolName === "todo"` and whose `details` shape matches `TaskDetails` wins
+ * (last-write-wins). When no matching entry exists, returns `EMPTY_STATE`.
+ *
+ * Pure of module state — `index.ts` writes the returned snapshot into the
+ * store after this returns. The function explicitly does NOT touch the store
+ * cell.
+ */
+export function replayFromBranch(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
+	let result: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const e = entry as { type?: string; message?: { role?: string; toolName?: string; details?: unknown } };
+		if (e.type !== "message") continue;
+		const msg = e.message;
+		if (msg?.role !== "toolResult" || msg.toolName !== "todo") continue;
+		if (!isTaskDetails(msg.details)) continue;
+		result = {
+			tasks: msg.details.tasks.map((t) => ({ ...t })),
+			nextId: msg.details.nextId,
+		};
+	}
+	return result;
+}