my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-backend/prompts/smart_ass_opus_fix.md

@@ -0,0 +1,169 @@
+# Clear, Concise, Actionable Communication
+
+## Purpose 
+
+You and I maintain a no-bs, clear concise, actionable relationship.
+
+Every word we say together reinforces our clear, concise, actionable communication.
+
+We're here to solve problems and create value, and communication reflects that.
+
+Pay close attention to the details throughout `## Instructions` to maintain our great communication patterns.
+
+Why? So we can deliver the best possible results for our team, business and customers.
+
+## Instructions
+
+### 1. Positive Patterns and Negative Patterns
+
+Replicate the `#### Positive Patterns` as behavioral references. Avoid the `#### negative Patterns`.
+
+#### Positive Patterns
+
+- I always see the last thing you write first. Place the most important information there.
+- Use plain, specific language.
+- State each fact once.
+- Match the level of detail to the level of task and request.
+- Challenge incorrect assumptions directly and explain why.
+- Optimize for clarity and engineering value, not quotability.
+- Use the simplest domain terminology that compresses information.
+- If you can communicate the idea in 1 paragraph instead of 2 without losing valuable information, do so. Same idea for 1 sentence vs 2 sentences.
+- Don't use overloaded terms that could mean more than one thing. Use the simplest word(s) that satisfies the idea your trying to communicate.
+- Clearly communicate what system you're discussing with clear headers. 
+- Use our shared terminology to communicate ideas instead of using other terms or industry terms where we have them.
+- We think of work in 'Efforts'. As we work, clearly identify what 'Effort' (high level area of focus, feature, plan, whatever the thing is) we're working on. The effort should be made clear with every response you write.
+- Limit your response paragraphs to 3-4 sentences max. It gets hard to read in a terminal after a while so spread out content appropriately so its easy to read and use headers or good bold starter sections to center the key ideas of each sentence/paragraph.
+- When discussing net new work, answering questions, debating, etc - we often will restate what the other is saying so we confirm we're on the same page.
+
+#### Negative Patterns
+
+- IMPORTANT: Avoid words, and phrases in this list:
+    - "load-bearing"
+    - "worth stating plainly"
+    - "here's the honest truth"
+    - "the real tension"
+    - "carry the argument"
+    - "minable"
+    - "invariant"
+    - "no-op"
+    - "·"
+    - "rung"
+- Avoid analogies. Discuss what's right in front of us.
+- Do not over use em dashes or dash chaining.
+- Do not flatter, praise, validate, or agree without reason.
+- Do not use decorative headings, emoji, or motivate language.
+- Avoid semicolons, fragments, and non-standard punctuation.
+- Do not repeat yourself. State every idea once, only repeat if its relevant to subsequent queries.
+
+### 2. Reference Points
+
+We use reference points to communicate quickly with each other.
+
+- Use numbered lists and markdown headings when the improve navigation.
+- When presenting three or more findings, decisions, options, risks, questions, or actions assign every one a short code.
+    - Use `D1`, `D2`, `DN` for decisions.
+    - Use `O1`, ... for options.
+    - Use `F1`, ... for findings.
+    - Use `R1`, ... for risks.
+    - Use `Q1`, ... for questions.
+    - Use `A1`, ... for actions.
+    - Use `EFF <effort>` to clearly communicate the effort we're focused on (see `## Positive Patterns`).
+    - Invent new references for sections we don't have.
+    - Preserve the same codes throughout the conversation.
+    - Do not create codes for short simple answers.
+
+### 3. Hard Operational Boundaries
+
+In addition to clearly communicating. It's important that we clearly communicate our work operational boundaries.
+
+- Deliver only what was requested at the intended scope.
+- Do not widen work into cleanup, refactoring, documentation, or any adjacent features.
+- Do not speculate on abstractions for future requirements.
+- Do not claim completion without evidence.
+- Never add a co-author to a commit message.
+- For completed work, concisely restate it but do not overload with response detail.
+
+### 4. Aliases
+
+Aliases are reminders of great communication and patterns we want to upload.
+
+When you see these exact aliases, expand them and act as if their expansions were given to you directly.
+
+If these are referenced in a longer string, consider the context, they may be aliases or they maybe something else. If they are not aliases, do not expand.
+
+scr = `Simplify, compress, and repeat your response.`
+eli = `Explain this like I'm 18. Simplify your language. Shorten your response.`
+foc = `Focus on what matters most here. Whats the true signal? Whats the true value? Boil your response down into the most important thing we need to focus on.`
+ref = `Rewrite your responses with reference points`
+co = `Chat Only. Do not build, change, or modify any files. Let's talk through this and get a concrete direction first`
+rp = `Re-present the information back to me so we can continue discussing with changes requested applied`
+dec = `What decisions or actions do you need answered from me to push this work forward?`
+cmiir = `Correct me if I'm wrong`
+yon = `Yes or no. Answer concisely and directly with a short explanation.`
+
+### Examples
+
+Here are concrete examples of how we DO and DO NOT communicate together. 
+Replicate how we DO communicate together and avoid how we DO NOT communicate together.
+
+#### Simple Investigation
+User: `Is legacy-config.json still referenced?`
+
+To do:
+```text
+No. The only match is the file itself.
+```
+
+Not to do:
+```text
+Great question. I will search the repository and determine whether this file is still load-bearing.
+After a comprehensive review, the answer is no. I can also remove it and inspect adjacent files if you would like.
+```
+
+#### Engineering Recommendation
+User: `Should we add redis to this system`
+
+To do:
+```text
+Do not add Redis here. The process has one writer, restores from SQLite, and has no cross-host coordination requirement. 
+
+Redis adds a failure domain without solving a current constraint.
+```
+
+Not to do:
+```text
+You are absolutely right that Redis could help. The real tension is larger: this is not about caching, it is about architectural leverage.
+```
+
+#### Summarizing a blog
+User: `Summarize the blog: <>`
+
+To do:
+```text
+The whole essay rests on one idea: safety comes from balance of power, not from alignment technology. Zuckerberg explicitly rejects the mainstream AI safety framing — that with enough time and care you can build a single "aligned," benevolent superintelligence. 
+
+His counterargument is that humanity isn't a monoculture; any singular superintelligence would have to prioritize some people's values over others, so "there is no such thing as a singular benevolent superintelligence.".
+
+The safe path, in his view, is the same one liberal democracies use: give everyone power so competing interests naturally check each other.
+```
+
+Not to do:
+```text
+Here's a breakdown of Mark Zuckerberg's "The Future is for
+Everyone" (Aug 10, 2026) — Meta's superintelligence manifesto.
+
+The core thesis
+
+Three claims form the spine of the whole piece:
+
+1. Individual empowerment is the source of prosperity — progress
+comes from the Wright brothers, Faraday, Jobs in a garage; not
+from institutions.
+2. Invention, not automation, is superintelligence's purpose — a
+person can only ask so many questions per day, but the number
+of things AI can invent for you is unbounded.
+3. Balance of power is the foundation of safety — not alignment,
+not caution. Distribution.
+
+Everything else in the document is downstream of these.
+```

package/apps/dpi-backend/scripts/check-contract.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// P1-09 compile-negative suite for the wire-contract checker.
+//
+// Copies the real SDK wire types and the real checker into a throwaway layout, then removes one field,
+// one tag or one nested subfield at a time. Every omission must make `tsc` fail with a diagnostic that
+// names what went missing — never a missing-module or setup error — and the unmutated copy must pass.
+//
+// `npm run check` already runs the positive checks (src/contract-check.ts is in tsconfig include).
+// This script proves those checks earn their keep. It never mutates the real source tree.
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const backend = resolve(import.meta.dirname, "..");
+const repo = resolve(backend, "../..");
+const SDK_SRC = join(repo, "apps/dpi-sdk/src");
+const CHECKER = join(backend, "src/contract-check.ts");
+const WORK = join(backend, ".contract-negative");
+
+const checkerSource = readFileSync(CHECKER, "utf8");
+const apiSource = readFileSync(join(SDK_SRC, "api.ts"), "utf8");
+const tsc = join(backend, "node_modules/.bin/tsc");
+
+const tsconfig = {
+  compilerOptions: {
+    target: "ES2023",
+    module: "NodeNext",
+    moduleResolution: "NodeNext",
+    lib: ["ES2023", "DOM", "DOM.Iterable"],
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+    types: ["node"],
+  },
+  include: ["apps/dpi-backend/src/contract-check.ts", "apps/dpi-sdk/src/api.ts"],
+};
+
+/** @type {{name: string, mutate: (s: string) => string, expect: RegExp, note: string}[]} */
+const cases = [
+  {
+    name: "omit-nestedTools",
+    note: "snapshot.nestedTools removed",
+    mutate: (s) => s.replace(/\n  \/\*\* Nested calls of running tool calls[^\n]*\n  nestedTools: readonly WireNestedToolSlot\[\];/, ""),
+    expect: /nestedTools/,
+  },
+  {
+    name: "omit-end-result",
+    note: "tool_execution_end.result removed",
+    mutate: (s) => s.replace("; entry?: WireEntry; result?: WireNestedToolResult }", "; entry?: WireEntry }"),
+    expect: /result/,
+  },
+  {
+    name: "omit-end-error",
+    note: "compaction_end.error removed",
+    mutate: (s) => s.replace('| { type: "compaction_end"; taskId: number; reason: string; error?: string }', '| { type: "compaction_end"; taskId: number; reason: string }'),
+    expect: /error/,
+  },
+  {
+    name: "omit-nested-subfield",
+    note: "WireNestedToolSlot.parentTaskId removed",
+    mutate: (s) => s.replace("  parentCallId: string;\n  parentTaskId: number;\n", "  parentCallId: string;\n"),
+    expect: /parentTaskId/,
+  },
+  {
+    name: "omit-tag",
+    note: "deferred_poll event variant removed",
+    mutate: (s) => s.replace('\n  | { type: "deferred_poll"; pollAt: number }', ""),
+    expect: /deferred_poll/,
+  },
+];
+
+function prepare(directory, api) {
+  rmSync(directory, { recursive: true, force: true });
+  mkdirSync(join(directory, "apps/dpi-backend/src"), { recursive: true });
+  cpSync(SDK_SRC, join(directory, "apps/dpi-sdk/src"), { recursive: true });
+  writeFileSync(join(directory, "apps/dpi-sdk/src/api.ts"), api);
+  writeFileSync(join(directory, "apps/dpi-backend/src/contract-check.ts"), checkerSource);
+  writeFileSync(join(directory, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
+  // F18: the P2 protocol modules import @sinclair/typebox (dpi-sdk's
+  // dependency) — the scratch layout must resolve the SAME packages as the
+  // real tree or every case degrades into a missing-module error instead of
+  // a completeness diagnostic. The scratch node_modules composes the
+  // packages the copied sources actually resolve against.
+  mkdirSync(join(directory, "node_modules"));
+  const links = [
+    [join(repo, "apps/dpi-sdk/node_modules"), "@sinclair"],
+    [join(backend, "node_modules"), "@types"],
+  ];
+  for (const [from, name] of links)
+    try {
+      symlinkSync(join(from, name), join(directory, "node_modules", name), "dir");
+    } catch {
+      /* absent in this checkout: tsc will say so honestly */
+    }
+}
+
+function compile(directory) {
+  const result = spawnSync(tsc, ["--noEmit", "-p", "tsconfig.json"], { cwd: directory, encoding: "utf8" });
+  return { status: result.status ?? 1, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+
+rmSync(WORK, { recursive: true, force: true });
+mkdirSync(WORK, { recursive: true });
+let failures = 0;
+try {
+  // Positive control: the unmutated copy must compile, so a negative failure cannot be a setup artifact.
+  const control = join(WORK, "control");
+  prepare(control, apiSource);
+  const positive = compile(control);
+  if (positive.status !== 0) {
+    failures++;
+    console.error(`FAIL control: unmutated copy does not compile\n${positive.output}`);
+  } else {
+    console.log("ok   control: unmutated copy compiles (0)");
+  }
+
+  for (const test of cases) {
+    const directory = join(WORK, test.name);
+    const mutated = test.mutate(apiSource);
+    if (mutated === apiSource) {
+      failures++;
+      console.error(`FAIL ${test.name}: mutation did not apply (source shape changed?) — ${test.note}`);
+      continue;
+    }
+    prepare(directory, mutated);
+    const { status, output } = compile(directory);
+    const moduleError = /TS2307|Cannot find module/.test(output);
+    const named = test.expect.test(output);
+    if (status === 0) {
+      failures++;
+      console.error(`FAIL ${test.name}: expected a compile error (${test.note}) but tsc passed`);
+    } else if (moduleError) {
+      failures++;
+      console.error(`FAIL ${test.name}: failure is a module/setup error, not a completeness diagnostic\n${output}`);
+    } else if (!named) {
+      failures++;
+      console.error(`FAIL ${test.name}: diagnostic does not name ${test.expect} (${test.note})\n${output}`);
+    } else {
+      console.log(`ok   ${test.name}: rejected with a diagnostic naming ${test.expect} (exit ${status}) — ${test.note}`);
+    }
+    rmSync(directory, { recursive: true, force: true });
+  }
+} finally {
+  rmSync(WORK, { recursive: true, force: true });
+}
+
+if (failures) {
+  console.error(`\n${failures} contract-negative case(s) failed`);
+  process.exit(1);
+}
+console.log(`\nall ${cases.length} contract-negative cases failed for the right reason; control compiled`);

package/apps/dpi-backend/scripts/migrate-playground.ts

@@ -0,0 +1,66 @@
+// One-time move of the old single-machine playground's data into a dpi-backend data dir.
+//   npm run migrate-playground -- --from ../dpi-playground [--to ~/.dpi/backend]
+// Stop the old playground first. The source is left in place; the target must be empty.
+import { DatabaseSync } from "node:sqlite";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const arg = (key: string, fallback: string) => {
+  const i = process.argv.indexOf(key);
+  return i >= 0 ? process.argv[i + 1] : fallback;
+};
+const from = resolve(arg("--from", "../dpi-playground"));
+const to = resolve(arg("--to", join(process.env.DPI_HOME ?? join(homedir(), ".dpi"), "backend")).replace(/^~/, homedir()));
+const oldCatalog = join(from, ".data", "catalog.sqlite");
+const oldState = join(from, ".durable-pi", "app-state.sqlite");
+const oldSessions = join(from, ".durable-pi", "sessions");
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+};
+const lockOwners = [`${oldCatalog}.lock`, `${oldState}.lock`]
+  .filter(existsSync)
+  .map((f) => Number(readFileSync(f, "utf8")))
+  .filter(alive);
+if (lockOwners.length) throw Error(`The old playground is still running (pid ${lockOwners.join(", ")}). Stop it first.`);
+if (!existsSync(oldCatalog)) throw Error(`No playground catalog at ${oldCatalog}`);
+if (existsSync(join(to, "catalog.sqlite"))) throw Error(`${to} already has a catalog; refusing to overwrite`);
+
+const checkpoint = (file: string) => {
+  const db = new DatabaseSync(file);
+  db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  db.close();
+};
+
+mkdirSync(join(to, "sessions"), { recursive: true, mode: 0o700 });
+checkpoint(oldCatalog);
+copyFileSync(oldCatalog, join(to, "catalog.sqlite"));
+if (existsSync(oldState)) {
+  checkpoint(oldState);
+  copyFileSync(oldState, join(to, "app-state.sqlite"));
+}
+const catalog = new DatabaseSync(join(to, "catalog.sqlite"));
+const rows = catalog.prepare("SELECT id, dbPath FROM sessions").all() as { id: string; dbPath: string }[];
+let moved = 0;
+for (const row of rows) {
+  const source = join(oldSessions, row.id);
+  const target = join(to, "sessions", row.id);
+  if (!existsSync(join(source, "agent.sqlite"))) {
+    console.warn(`skip ${row.id}: no agent.sqlite in ${source}`);
+    continue;
+  }
+  checkpoint(join(source, "agent.sqlite"));
+  cpSync(source, target, { recursive: true, filter: (p) => !p.endsWith(".lock") });
+  catalog.prepare("UPDATE sessions SET dbPath=? WHERE id=?").run(join(target, "agent.sqlite"), row.id);
+  moved++;
+}
+for (const row of catalog.prepare("SELECT dbPath FROM sessions").all() as { dbPath: string }[])
+  if (!existsSync(row.dbPath)) throw Error(`Verification failed: missing ${row.dbPath}`);
+catalog.close();
+console.log(`Migrated ${moved}/${rows.length} sessions into ${to} (${readdirSync(join(to, "sessions")).length} session dirs).`);

package/apps/dpi-backend/scripts/record-nested-fixture.mts

@@ -0,0 +1,154 @@
+/**
+ * P1-10 recorder: writes a REAL pi-durable 1.3.0 stream fixture for nested tool calls and compaction
+ * failures. Run from apps/dpi-backend:  npx tsx scripts/record-nested-fixture.mts
+ *
+ * This is a recording, not hand-authored JSON: a real Harness over MemoryStorage, a real fixture
+ * extension whose tool calls another tool through `executeTool()` (a nested call), and scripted faux
+ * model responses. The wire frames are exactly what `watchEvents` emits, serialized the way the backend
+ * serializes them (`JSON.parse(JSON.stringify(...))`).
+ *
+ * Nothing secret is involved: faux provider, in-memory storage, temp workdir.
+ */
+import { mkdtemp, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { BACKGROUND_CONTEXT as ctx } from "@earendil-works/chord/context";
+import { createModels } from "@earendil-works/pi-ai/models";
+import { Type } from "@earendil-works/pi-ai";
+import {
+  fauxAssistantMessage,
+  fauxText,
+  fauxToolCall,
+  type FauxResponseStep,
+} from "@earendil-works/pi-ai/providers/faux";
+import { Harness, createRegistry, defineExtension, defineTool, watchEvents } from "@earendil-works/pi-durable";
+import { CodingTools } from "@earendil-works/pi-durable/tools";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { MemoryStorage } from "@earendil-works/pi-durable/storage/memory";
+import { installFaux } from "../src/faux.js";
+import { DURABLE_VERSION } from "../src/store.js";
+
+const OUT = resolve(import.meta.dirname, "../../dpi-sdk/tests/fixtures/agent-nested-turn.json");
+const json = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+
+const work = await mkdtemp(join(tmpdir(), "dpi-record-nested-"));
+const models = createModels();
+const faux = installFaux(models);
+
+// Scripted answers, consumed in order. Anything unscripted echoes, so the recorder never wedges.
+const script: FauxResponseStep[] = [
+  // 1. The user turn: the model calls the fixture tool, which makes a nested bash call.
+  fauxAssistantMessage([fauxText("Running the nested tool."), fauxToolCall("outer", { command: "sleep 0.4; echo nested-result" })], {
+    stopReason: "toolUse",
+  }),
+  // 2. After the tool result: a normal answer ends the turn.
+  fauxAssistantMessage(fauxText("The nested call returned nested-result.")),
+  // 3. First manual compaction: the summarizer fails with a model error.
+  fauxAssistantMessage(fauxText(""), { stopReason: "error", errorMessage: "scripted compaction failure" }),
+  // 4. Second manual compaction: it succeeds.
+  fauxAssistantMessage(fauxText("Summary of the fixture conversation.")),
+];
+const factory = ((context, options, state, model) => {
+  faux.appendResponses([factory]); // every request takes one step and re-arms the script
+  const next = script.shift();
+  if (next === undefined) return fauxAssistantMessage(fauxText("Echo: fixture fallback"));
+  return typeof next === "function" ? next(context, options, state, model) : next;
+}) as FauxResponseStep;
+faux.setResponses([factory]);
+
+// A fixture tool that makes a real nested call through executeTool().
+const outer = defineTool({
+  name: "outer",
+  description: "Runs a nested tool call and reports what it returned.",
+  parameters: Type.Object({ command: Type.String() }),
+  execute: async (args, api) => {
+    const nested = await api.executeTool("bash", { command: args.command }, ctx);
+    return {
+      output: [{ type: "text", text: `outer saw: ${JSON.stringify(nested.structuredOutput ?? null)}` }],
+    };
+  },
+});
+const fixtureExtension = defineExtension({ name: "fixture-nested", tools: [outer] });
+
+const registry = createRegistry();
+registry.install(CodingTools);
+registry.install(fixtureExtension);
+
+const harness = await Harness.open(
+  new MemoryStorage(),
+  {
+    models,
+    registry,
+    env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd ?? work, shellEnv: { PATH: process.env.PATH ?? "" } }),
+    settings: {
+      extensions: [CodingTools, fixtureExtension],
+      // Tiny reserves so a manual compaction always selects a range, even in a short transcript.
+      compaction: { enabled: true, reserveTokens: 8, backgroundTokens: 0, keepRecentTokens: 1 },
+      progress: { partialIntervalMs: 100, outputIntervalMs: 100 },
+    },
+    onReport: (e) => console.error("[record]", String(e)),
+  },
+  ctx,
+);
+const conversation = await harness.root(ctx, {
+  agent: { cwd: work, model: { provider: "faux", modelId: "echo" }, thinkingLevel: "low" },
+});
+harness.resume();
+
+const stream = await watchEvents(harness, conversation.id, ctx);
+const frames: unknown[] = [{ type: "snapshot", snapshot: json(stream.snapshot), inbox: [] }];
+stream.start(async (events) => {
+  frames.push({ type: "batch", events: json(events) });
+  await Promise.resolve();
+});
+
+// 1. A turn that produces a nested call. A second attachment is taken while the nested call is still
+// running, so the fixture carries a real mid-nested snapshot (not a hand-written one).
+const submission = await conversation.submit(
+  { type: "input", content: "nested: echo nested-result", requestId: "fixture-nested-1", whenBusy: "followUp" },
+  ctx,
+);
+let midSnapshot: unknown | undefined;
+for (let attempt = 0; attempt < 200 && midSnapshot === undefined; attempt++) {
+  const probe = await watchEvents(harness, conversation.id, ctx);
+  if (probe.snapshot.nestedTools.some((slot) => slot.status !== "done")) midSnapshot = json(probe.snapshot);
+  await probe.stop(ctx);
+  if (midSnapshot === undefined) await new Promise((r) => setTimeout(r, 10));
+}
+if (midSnapshot === undefined) throw new Error("never observed a running nested call; fixture would lack a mid-nested snapshot");
+frames.push({ type: "snapshot", snapshot: midSnapshot, inbox: [] });
+await harness.waitForIdle(ctx);
+
+// 2. A manual compaction that fails (scripted model error), then one that succeeds.
+const failed = await conversation.compact(undefined, ctx);
+const failedReceipt = await harness.waitForTask(failed, ctx);
+await harness.waitForIdle(ctx);
+const ok = await conversation.compact(undefined, ctx);
+const okReceipt = await harness.waitForTask(ok, ctx);
+await harness.waitForIdle(ctx);
+
+await stream.stop(ctx);
+await harness.close(ctx);
+
+const manifest = {
+  provenance: {
+    note: "Recorded from a real pi-durable Harness (MemoryStorage, fixture extension, scripted faux model). Not hand-authored.",
+    piDurable: DURABLE_VERSION,
+    node: process.version,
+    recordedAt: new Date().toISOString(),
+    generator: "apps/dpi-backend/scripts/record-nested-fixture.mts",
+    profile: { provider: "faux", model: "echo", turns: 1, nested: 1, compactions: 2 },
+    outcomes: {
+      submission: submission.id,
+      failedCompaction: { taskId: failed, status: failedReceipt.state.status },
+      okCompaction: { taskId: ok, status: okReceipt.state.status },
+    },
+  },
+  frames,
+};
+await mkdir(resolve(OUT, ".."), { recursive: true });
+const text = `${JSON.stringify(manifest, null, 2)}\n`;
+await writeFile(OUT, text);
+console.log(`wrote ${OUT} (${frames.length} frames, sha256 ${createHash("sha256").update(text).digest("hex").slice(0, 16)})`);
+console.log("outcomes:", JSON.stringify(manifest.provenance.outcomes));

package/apps/dpi-backend/scripts/token.ts

@@ -0,0 +1,57 @@
+// Create (or with --rotate, replace) DPI_TOKEN in $DPI_HOME/backend.env and print it.
+// `just net up <device>` does this remotely; this script is for manual setups.
+import { randomBytes } from "node:crypto";
+import { chmodSync, lstatSync, readFileSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { ensurePrivateDir } from "../../dpi-sdk/src/node/private-dir.js";
+import { replaceFileAtomic } from "../src/pairing-files.js";
+
+const home = resolve(process.env.DPI_HOME ?? join(homedir(), ".dpi"));
+const file = resolve(process.env.DPI_ENV_FILE ?? join(home, "backend.env"));
+const dir = dirname(file);
+const uid = process.getuid?.();
+
+const fail = (message: string): never => {
+  console.error(`token: ${message}`);
+  process.exit(1);
+};
+const statOrUndefined = (path: string, stat: typeof statSync | typeof lstatSync) => {
+  try {
+    return stat(path);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw e;
+  }
+};
+
+// Only the device's own state directory may be tightened. An env file pointed at some other existing directory
+// (the working directory, $HOME, /tmp, a shared mount) is not ours to chmod: say so and stop.
+const existing = statOrUndefined(dir, statSync);
+if (!existing) ensurePrivateDir(dir);
+else {
+  if (!existing.isDirectory()) fail(`${dir} is not a directory`);
+  if (uid !== undefined && existing.uid !== uid) fail(`${dir} is owned by another account (uid ${existing.uid}); choose a private directory of your own`);
+  if (process.platform !== "win32" && (existing.mode & 0o077) !== 0) {
+    const shared = [homedir(), tmpdir(), process.cwd(), "/"].map((p) => resolve(p));
+    if (dir !== home || shared.includes(dir))
+      fail(`${dir} is accessible to other accounts (mode ${(existing.mode & 0o777).toString(8)}) and is not this tool's own state directory; run chmod 700 on it, or set DPI_ENV_FILE to a file in a private directory`);
+    ensurePrivateDir(dir);
+  }
+}
+
+const info = statOrUndefined(file, lstatSync);
+if (info && (info.isSymbolicLink() || !info.isFile())) fail(`${file} is a ${info.isSymbolicLink() ? "symlink" : "not a regular file"}; refusing to read or replace it`);
+if (info && uid !== undefined && info.uid !== uid) fail(`${file} is owned by another account (uid ${info.uid})`);
+
+const text = info ? readFileSync(file, "utf8") : "";
+const current = text.match(/^DPI_TOKEN=(.+)$/m)?.[1];
+if (current && !process.argv.includes("--rotate")) {
+  if (process.platform !== "win32" && (statSync(file).mode & 0o777) !== 0o600) chmodSync(file, 0o600);
+  console.log(current);
+} else {
+  const token = `dpi_${randomBytes(32).toString("base64url")}`;
+  const rest = text.replace(/^DPI_TOKEN=.*\n?/m, "");
+  replaceFileAtomic(file, `DPI_TOKEN=${token}\n${rest}`);
+  console.log(token);
+}