@jxsuite/studio 5.2.0 → 5.4.0

package/src/publish/deploy-checklist.ts

@@ -9,19 +9,19 @@
  * different command owned by a different module. Nothing in Studio held the chain, so no surface
  * could say which link was missing.
  *
- * This module is the chain (plan §9.5):
+ * This module is the chain (`docs/studio/publish.md`):
  *
  * - {@link deployChecklist} is the ordered prerequisite list, each step carrying **the command that
  *   satisfies it** rather than a sentence telling the reader to go and find one;
  * - {@link deployChecklistView} is its projection and {@link syncDeployChecklist} mounts the document
  *   that draws it (`surfaces/panel-deploy-checklist.json`), in the Bottom dock's **Activity** tab
- *   because a deploy is a long operation with a log and the dock cap is four (§2 principle 9). It
- *   draws in the Activity tab's vocabulary — the same row, the same ordered steps, the same glyphs
- *   — for the same reason: a fifth visual idiom for "an ordered list of stages that finish" would
- *   be a second design of a thing the tab already has;
+ *   because a deploy is a long operation with a log and the dock cap is four
+ *   (`studio-ui-guidelines.md` §12.2). It draws in the Activity tab's vocabulary — the same row,
+ *   the same ordered steps, the same glyphs — for the same reason: a fifth visual idiom for "an
+ *   ordered list of stages that finish" would be a second design of a thing the tab already has;
  * - {@link deployStatusItem} is the status bar's project-field item, whose **label is the next
  *   blocking prerequisite** — the shortcut and the explanation in one 24px item, and ambient state
- *   rather than a transient message, which is the only thing that bar carries (§3.2 ⑫).
+ *   rather than a transient message, which is the only thing that bar carries (§16.2).
  *
  * **A step it cannot answer says `unknown`.** `services/references.ts` established the rule and it
  * matters more here: "no deployment" and "we have not asked Cloudflare" look identical from inside
@@ -81,8 +81,9 @@ function currentConfig(): ProjectConfig | null {
 /**
  * The connected provider block, or `undefined`.
  *
- * Exported because the Publish panel asks the same question and P6's lesson was that two copies of
- * one derivation drift apart in silence — there is one reader of `build.deploy` in the app.
+ * Exported because the Publish panel asks the same question and the shell redesign's configuration
+ * phase taught that two copies of one derivation drift apart in silence — there is one reader of
+ * `build.deploy` in the app.
  */
 export function currentDeploy(): DeployConfig | undefined {
   return currentConfig()?.build?.deploy;
@@ -336,7 +337,7 @@ function stepView(step: DeployStep): DeployStepRowView {
  *
  * A command the registry does not have, or whose `when` is false, draws NOTHING rather than a dead
  * label. The status bar's projection takes the same position for the same reason: a surface may
- * choose whether to show a command, never whether it exists (§12.4).
+ * choose whether to show a command, never whether it exists (`studio-ui-guidelines.md` §12.3).
  */
 function actionView(
   step: DeployStep | null,
@@ -415,7 +416,7 @@ const CHECKLIST_SURFACE = { project: deployChecklistView, runAction: runNextStep
  * Rendered ABOVE the operation feed rather than as an entry in it: an activity is something that
  * happened, and this is something that has not. It carries no `data-jx-region` stamp — the region
  * is `dock.bottom/panel:activity`, which the dock derives, and a hand-stamped leaf is a committed
- * budget (§13.2) that this does not need to spend.
+ * budget (`scripts/screenshots/README.md`, "The region grammar") that this does not need to spend.
  *
  * @param host The dock body element the tab was rendered into.
  */

package/src/publish/publish-commands.ts

@@ -1,5 +1,6 @@
 /**
- * Publish-commands.ts — the `Publish:` family (plan §9.5), defined beside the deploy it drives.
+ * Publish-commands.ts — the `Publish:` family (`docs/studio/publish.md`), defined beside the deploy
+ * it drives.
  *
  * Two unrelated operations were called "Publish" and neither was a command. `publishToGithub`
  * created a git repository; `openPublishPanel` connected Cloudflare Pages — and it had **zero call
@@ -16,7 +17,7 @@
  * | `publish.openDashboard` | opens the connected Pages project on Cloudflare           |
  *
  * **`runDeploy` is an Activity, not a toast.** A deploy pushes a branch and then waits on a build
- * that is happening somewhere else; that is the definition of the long operation §7.3 gave the
+ * that is happening somewhere else; that is the definition of the long operation §16.4 gave the
  * Activity tab, and `fail()` raises the Problem so the failure outlives the run and carries a
  * Retry. The caller therefore never also notifies (§16).
  *
@@ -42,7 +43,7 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
  * Six attempts five seconds apart: a Pages build takes minutes, so this is not "wait for the build"
  * — it is "wait for the deployment RECORD", which appears within seconds of the push. The activity
  * says which of the two it is waiting for, because a progress line that implies the former and
- * delivers the latter is the dishonesty §7.3 exists to end.
+ * delivers the latter is the dishonesty §16.4 exists to end.
  */
 export const DEPLOY_POLL = { attempts: 6, delayMs: 5000 } as const;
 
@@ -135,7 +136,7 @@ export async function runDeploy(
  *
  * `enablement` reads `platformSupportsPublish()` rather than a `capability.*` key because there is
  * no `publish` capability yet — adding one is a `commands/context.ts` + `commands/live-context.ts`
- * change, and §5.2 is explicit that PAL differences belong there. Until it exists this is the one
+ * change, and §13.4 is explicit that PAL differences belong there. Until it exists this is the one
  * `if (platform.x)` the family carries, in the one place a reader looks for it.
  */
 export function publishCommands(): AnyCommand[] {
@@ -157,8 +158,8 @@ export function publishCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       // `when` already asked about the project.
       enablement: () => platformSupportsPublish(),
-      /* No `aiTool`, by §12.4's second deletion rule: an auth flow that waits on a person, with
-         credentials. */
+      /* No `aiTool`, by `studio-ui-guidelines.md` §12.4's second rule: an auth flow that waits on a
+         person, with credentials. */
       run: async () => {
         const { openPublishPanel } = await import("./publish-panel");
         openPublishPanel();
@@ -177,8 +178,8 @@ export function publishCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       enablement: (ctx) =>
         ctx.project.isRepo && currentDeploy() !== undefined && platformSupportsPublish(),
-      /* No `aiTool`, by §12.4's third deletion rule: remote and irreversible, the same class as
-         `packages.remove`. */
+      /* No `aiTool`, by `studio-ui-guidelines.md` §12.4's third rule: remote and irreversible, the
+         same class as `packages.remove`. */
       run: async () => {
         await runDeploy();
       },

package/src/services/a11y-report.ts

@@ -29,7 +29,7 @@
  * alt, an aria reference to an id nothing has, a tab, menu item or option outside its container, a
  * tablist with no selected tab, an unnamed dialog, aria-activedescendant on an element that cannot
  * take focus — so `jx validate`, the kit's conformance tests and this report judge a document alike
- * (spec §8.8). What stays here is what needs the whole page rather than a node: the heading
+ * (`spec.md` §8.8). What stays here is what needs the whole page rather than a node: the heading
  * outline, duplicate ids, the document language, link wording, autocomplete purposes and media.
  *
  * @docs studio/interface/problems-and-progress

package/src/services/ai-ask.ts

@@ -25,7 +25,6 @@
 
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
 import { reactive } from "../reactivity";
-import { currentToolCallId, turnSignal } from "./ai-turn-signal";
 
 import type { ToolRegistry } from "@jxsuite/ai/tools";
 
@@ -81,17 +80,17 @@ export function isAwaitingAnswer(): boolean {
  * Register a question and suspend until it is settled.
  *
  * @param {PendingAsk} ask
+ * @param {AbortSignal} [signal] - The asking call's signal. Without one the question can still be
+ *   settled by {@link cancelAsk}, but a Stop would leave the turn awaiting a promise nothing could
+ *   resolve.
  * @returns {Promise<AskAnswer>} Resolves on an answer, a skip, or the turn being stopped (`{
  *   answer: null, skipped: false }` — the shape the tool reports as a failure).
  */
-export function askUser(ask: PendingAsk): Promise<AskAnswer> {
+export function askUser(ask: PendingAsk, signal?: AbortSignal): Promise<AskAnswer> {
   return new Promise<AskAnswer>((resolve) => {
     state.pending = ask;
     settle = resolve;
 
-    /* The turn's signal, not a parameter: `ToolRegistry.execute` has nowhere to pass one. Without
-       this, Stop would leave the loop awaiting a promise nothing could ever resolve. */
-    const signal = turnSignal();
     if (signal?.aborted) {
       clear();
       resolve({ answer: null, skipped: false });
@@ -163,10 +162,26 @@ export function resetAsk(): void {
  *
  * @param {Pick<ToolRegistry, "register">} registry
  */
-export function registerAskTool(registry: Pick<ToolRegistry, "register">): void {
+/** What the host that registers the question tool may hook. */
+export interface AskToolOptions {
+  /**
+   * Called once a question has been put to the author, before the turn waits on the answer. A host
+   * saves the conversation here: a turn suspended on a person may wait for as long as they like,
+   * and a reload in the meantime must still find the question to restore as open (`specs/ai.md`
+   * §3.4).
+   */
+  onPending?: () => void;
+}
+
+export function registerAskTool(
+  registry: Pick<ToolRegistry, "register">,
+  { onPending }: AskToolOptions = {},
+): void {
   registry.register(
     createToolDefinition({
       name: "ask_user",
+      // It suspends the turn on the author, so a round that only asked spends no work budget.
+      interactive: true,
       description:
         "Pause and put a question to the user; the turn waits for their reply and resumes with " +
         "it. Use it ONLY for a judgement that is genuinely theirs — which pages matter, whether to " +
@@ -196,7 +211,7 @@ export function registerAskTool(registry: Pick<ToolRegistry, "register">): void
         },
         required: ["question"],
       },
-      execute: async (args) => {
+      execute: async (args, ctx) => {
         /* Everything `unknown`, and every field narrowed by `typeof` rather than by `?.`. The
            registry's `validate()` is "a lightweight structural check, not a JSON Schema validator",
            `strict: false` skips it entirely, and this tool may be registered into someone else's
@@ -219,15 +234,23 @@ export function registerAskTool(registry: Pick<ToolRegistry, "register">): void
               .slice(0, MAX_OPTIONS)
           : [];
 
-        const { answer, skipped } = await askUser({
-          context: typeof context === "string" ? context.trim() : "",
-          /* The tool-call id, so the chip the transcript draws and the question this registers are
-             the same thing. Without it a restored, permanently unanswered question would render
-             identically to the live one. */
-          id: currentToolCallId(),
-          options: choices,
-          question: question.trim(),
-        });
+        const answering = askUser(
+          {
+            context: typeof context === "string" ? context.trim() : "",
+            /* The tool-call id, so the chip the transcript draws and the question this registers
+               are the same thing. Without it a restored, permanently unanswered question would
+               render identically to the live one. */
+            id: ctx.callId,
+            options: choices,
+            question: question.trim(),
+          },
+          ctx.signal,
+        );
+        // The question is published by now (`askUser` sets it synchronously); the answer is not.
+        if (isAwaitingAnswer()) {
+          onPending?.();
+        }
+        const { answer, skipped } = await answering;
 
         if (skipped) {
           /* A success: the model asked, and "you decide" is an answer. Rendering it as a failure

package/src/services/ai-command-tools.ts

@@ -59,14 +59,19 @@
  * @license MIT
  */
 
-import { toolError } from "@jxsuite/ai/tools";
-import type { ToolDefinition, ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
+import { createToolContext, toolError } from "@jxsuite/ai/tools";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolRegistry,
+  ToolResult,
+  WriteLedger,
+} from "@jxsuite/ai/tools";
 import { activeRegistry } from "../commands/active-registry";
 import { argsSchema } from "../commands/command-args";
 import { inCanvas } from "../commands/context";
 import { toRaw } from "../reactivity";
 import { projectState } from "../state";
-import { recordWrite } from "./ai-writes";
 import { reportDocumentWrite, snapshotBeforeWrite } from "./ai-write-report";
 import type { WriteReportDeps, WriteSnapshot } from "./ai-write-report";
 import type { CommandContext } from "../commands/context";
@@ -198,7 +203,7 @@ function projected(registry: CommandRegistry): AnyCommand[] {
 function definitionOf(
   registry: CommandRegistry,
   command: AnyCommand,
-  execute: (name: string, args: object) => Promise<ToolResult>,
+  execute: (name: string, args: object, ctx: ToolContext) => Promise<ToolResult>,
 ): ToolDefinition | undefined {
   const tool = command.aiTool!;
   let parameters: object;
@@ -217,7 +222,7 @@ function definitionOf(
     parameters: parameters as ToolDefinition["parameters"],
     strict: false,
     llmStrict: false,
-    execute: (args) => execute(tool.name, args),
+    execute: (args, ctx) => execute(tool.name, args, ctx),
   };
 }
 
@@ -235,7 +240,7 @@ function definitionOf(
  */
 export function advertisedCommandTools(
   registry: CommandRegistry,
-  execute: (name: string, args: object) => Promise<ToolResult> = async (name) =>
+  execute: (name: string, args: object, ctx: ToolContext) => Promise<ToolResult> = async (name) =>
     toolError(`Tool "${name}" was listed without an executor.`),
 ): ToolDefinition[] {
   const definitions: ToolDefinition[] = [];
@@ -324,13 +329,18 @@ function defaultPaths(command: AnyCommand, tab: Tab | null): string[] {
  * had — and files nothing, because the ledger names files that changed; `undefined` is a report
  * that named none and takes the record's defaults.
  */
-function fileLedger(command: AnyCommand, tab: Tab | null, wrote?: readonly string[]): void {
+function fileLedger(
+  ledger: WriteLedger,
+  command: AnyCommand,
+  tab: Tab | null,
+  wrote?: readonly string[],
+): void {
   if (command.undo === undefined) {
     return;
   }
   const disk = command.undo === "none";
   for (const path of wrote ?? defaultPaths(command, tab)) {
-    recordWrite({ disk, ok: true, path, tool: command.title });
+    ledger.record({ disk, ok: true, path, tool: command.title });
   }
 }
 
@@ -349,13 +359,17 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
   }
 
   /**
-   * Run one projected record as the agent — the whole of §3 of the design.
+   * Run one projected record as the agent — the whole of `ai.md` §3.6.
    *
    * @param {string} name
    * @param {object} received
    * @returns {Promise<ToolResult>}
    */
-  async function execute(name: string, received: object): Promise<ToolResult> {
+  async function execute(
+    name: string,
+    received: object,
+    ctx: ToolContext = createToolContext(),
+  ): Promise<ToolResult> {
     const registry = activeRegistry();
     const command = commandFor(name);
     if (!registry || !command) {
@@ -426,7 +440,7 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
          Left to the loop, the throw would be labelled "Failed to parse arguments" and the ledger
          would never be filed. So the ledger is filed from `undo`'s defaults — the report that would
          have named the paths is the thing that failed — and the model is told both halves. */
-      fileLedger(command, tab, projectUnchanged ? [] : undefined);
+      fileLedger(ctx.ledger, command, tab, projectUnchanged ? [] : undefined);
       const message = error instanceof Error ? error.message : String(error);
       return { error: `${command.title} ran, but its report failed: ${message}`, success: false };
     }
@@ -442,7 +456,7 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
         summary = `${command.title} changed nothing: project.json is exactly as it was.`;
       }
     }
-    fileLedger(command, tab, wrote);
+    fileLedger(ctx.ledger, command, tab, wrote);
     if (tab && snapshot) {
       const verdict = await reportDocumentWrite(tab, snapshot, summary, deps);
       if (!verdict.success) {
@@ -530,9 +544,9 @@ export function composeToolRegistries(hand: ToolRegistry, commands: ToolRegistry
         ? side.validate(name, args)
         : { valid: false, errors: [`Unknown tool: "${name}"`] };
     },
-    async execute(name, args) {
+    async execute(name, args, ctx) {
       const side = sideOf(name);
-      return side ? side.execute(name, args) : toolError(`Unknown tool: "${name}"`);
+      return side ? side.execute(name, args, ctx) : toolError(`Unknown tool: "${name}"`);
     },
   };
 }

package/src/services/ai-import-tools.ts

@@ -28,18 +28,12 @@ import { workspace } from "../workspace/workspace";
 import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { clearPendingImportBrief, pendingImportBrief } from "./import-seed";
-import {
-  abortImportRun,
-  beginImportRun,
-  finishImportRun,
-  importRun,
-  recordImportProgress,
-} from "./import-run";
+import type { ImportBrief } from "./import-seed";
+import { abortImportRun, beginImportRun, finishImportRun, importRun } from "./import-run";
 import { adoptCreatedProject } from "./project-adoption";
 import type { AdoptOutcome } from "./project-adoption";
-import { currentToolCallId, turnSignal } from "./ai-turn-signal";
 
-import type { ToolRegistry } from "@jxsuite/ai/tools";
+import type { JsonValue, ToolRegistry } from "@jxsuite/ai/tools";
 import type { Tab } from "../tabs/tab";
 import type { ImportBreakpointPolicy, ImportReadyEvent, ImportSiteSummary } from "../types";
 
@@ -72,6 +66,11 @@ export interface ImportToolsCtx {
   adoptProject?: (root: string) => Promise<void>;
   /** Fired once adoption is VERIFIED — the session store re-keys the live chat here. */
   onProjectAdopted?: (root: string) => void;
+  /**
+   * The New Project Import form's brief, when the run started there. Defaults to the one the form
+   * stores (`services/import-seed.ts`); a host with no form binds its own.
+   */
+  brief?: { read: () => ImportBrief | null; clear: () => void };
 }
 
 function clamp(value: number, min: number, max: number): number {
@@ -151,19 +150,15 @@ function destinationProblem(destination: string): string | null {
 }
 
 /**
- * One run has already succeeded in this session.
+ * The session fact that one run has already succeeded in this conversation.
  *
  * Not the same question as `workspace.projectRoot`, and that is the whole reason it exists: on
  * desktop, adoption may open the project in ANOTHER window, leaving this one's root empty — so the
  * `no-project` tier would happily advertise a second import over the top of the first.
- * `create_project` has the identical hazard today.
+ * `create_project` has the identical hazard today. A session fact rather than a module flag, and it
+ * lasts as the flag did: New Chat starts with none, and opening another chat keeps it.
  */
-let imported = false;
-
-/** Forget that an import ran. New Chat, and tests. */
-export function resetImportGuard(): void {
-  imported = false;
-}
+const IMPORT_DONE = "import.done";
 
 /**
  * A compact, factual account of the run for the model to reason about — and to ask about.
@@ -258,7 +253,12 @@ function describeRun(id: string, root: string, summary?: ImportSiteSummary): str
  */
 export function registerImportTools(
   registry: Pick<ToolRegistry, "register">,
-  { getTab, adoptProject, onProjectAdopted }: ImportToolsCtx,
+  {
+    getTab,
+    adoptProject,
+    onProjectAdopted,
+    brief: briefStore = { clear: clearPendingImportBrief, read: pendingImportBrief },
+  }: ImportToolsCtx,
 ): void {
   registry.register(
     createToolDefinition({
@@ -334,7 +334,7 @@ export function registerImportTools(
         },
         required: ["url"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const {
           url,
           directory,
@@ -364,7 +364,7 @@ export function registerImportTools(
             "A project is already open in this window — import_site is only for bootstrapping.",
           );
         }
-        if (imported) {
+        if (ctx.session.get(IMPORT_DONE) === true) {
           return toolError(
             "A site has already been imported in this conversation. Start a new chat to import " +
               "another, or use the file tools on the project that was created.",
@@ -385,7 +385,7 @@ export function registerImportTools(
           return toolError("The url must start with http:// or https://.");
         }
 
-        const brief = pendingImportBrief();
+        const brief = briefStore.read();
         const requested = typeof directory === "string" ? directory.trim() : "";
         if (requested && brief && requested !== brief.directory) {
           /* The wizard's Location field is the user's answer to "where does this go". A model that
@@ -410,16 +410,23 @@ export function registerImportTools(
           return toolError(problem);
         }
 
-        const id = currentToolCallId();
+        const id = ctx.callId;
         const signal = beginImportRun(id, { directory: destination, url: target.href });
-        /* The turn's own signal too. `assistant.stop` aborts the request through `abortImportRun`,
+        /* The call's own signal too. `assistant.stop` aborts the request through `abortImportRun`,
            but that is not the only way a turn ends: the loop's signal can be aborted directly, and
            a run left going after its turn died would keep a headless browser open for minutes with
-           nothing left to receive the result. */
-        turnSignal()?.addEventListener("abort", () => {
+           nothing left to receive the result.
+
+           It stops THIS run and nothing after it, so it is removed the moment the run settles: left
+           on the signal, a Stop later in the same turn (a question after the import, say) rewrote
+           the finished run as stopped. The loop also unlinks the call's signal once the call
+           settles, so a later Stop reaches it no more than it reaches the listener. */
+        const callSignal = ctx.signal;
+        const stopRun = () => {
           abortImportRun();
           finishImportRun(id, { status: "stopped" });
-        });
+        };
+        callSignal.addEventListener("abort", stopRun, { once: true });
 
         const apiKey = getOpenAiKey();
         const baseUrl = getBaseUrl();
@@ -479,11 +486,14 @@ export function registerImportTools(
               ...(baseUrl ? { baseUrl } : {}),
               ...(model ? { model } : {}),
             },
-            (evt) => recordImportProgress(id, evt),
+            (evt) => {
+              ctx.progress(evt as unknown as JsonValue);
+            },
             signal,
             onReady,
           );
         } catch (error) {
+          callSignal.removeEventListener("abort", stopRun);
           const message = error instanceof Error ? error.message : String(error);
           if (signal.aborted) {
             finishImportRun(id, { error: message, status: "stopped" });
@@ -502,9 +512,13 @@ export function registerImportTools(
           );
         }
 
+        callSignal.removeEventListener("abort", stopRun);
         finishImportRun(id, { status: "done" });
-        imported = true;
-        clearPendingImportBrief();
+        /* The imported project is on disk from here, and no undo reaches it: it is what the turn
+           changed, whichever window ends up opening it. */
+        ctx.ledger.record({ disk: true, ok: true, path: result.root, tool: "import_site" });
+        ctx.session.set(IMPORT_DONE, true);
+        briefStore.clear();
 
         /* The early adoption if there was one, otherwise adopt now: a backend that sends no `ready`
            line is not broken, it is older, and the project must still open. */

package/src/services/ai-project-tools.ts

@@ -16,7 +16,7 @@
 
 import { createToolDefinition } from "@jxsuite/ai/tools";
 import type { CreateProjectDestination } from "../types";
-import type { ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
+import type { ToolRegistry } from "@jxsuite/ai/tools";
 import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
 import { workspace } from "../workspace/workspace";
@@ -25,8 +25,8 @@ import type { Tab } from "../tabs/tab";
 import { adoptCreatedProject } from "./project-adoption";
 import { translateValidationError } from "./ai-tools";
 import { validateDoc, validateProjectConfig } from "./jx-validate";
-import { recordWrite } from "./ai-writes";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
+import { invalidPathResult, normalizeRelPath } from "./project-path";
 
 /** Directories the file tools never descend into or report. */
 const EXCLUDED_DIRS = new Set(["node_modules", "dist", ".git", ".jx-cache"]);
@@ -39,34 +39,6 @@ const WRITE_CAP_BYTES = 256 * 1024;
 
 const NOT_UNDOABLE = "(saved to disk; not undoable with Cmd+Z)";
 
-/**
- * Normalize a project-relative path, or return null when it escapes the project (absolute paths,
- * `..` segments, drive letters). The server re-checks; this keeps the error actionable.
- */
-export function normalizeRelPath(path: unknown): string | null {
-  if (typeof path !== "string" || !path.trim()) {
-    return null;
-  }
-  let p = path.trim().replaceAll("\\", "/");
-  while (p.startsWith("./")) {
-    p = p.slice(2);
-  }
-  if (p.startsWith("/") || p.startsWith("~") || /^[A-Za-z]:/.test(p)) {
-    return null;
-  }
-  if (p.split("/").includes("..")) {
-    return null;
-  }
-  return p;
-}
-
-function pathError(path: unknown): ToolResult {
-  return {
-    success: false,
-    error: `Invalid path ${JSON.stringify(path)} — use a path relative to the project root (no leading "/", no "..").`,
-  };
-}
-
 /**
  * Whether a project-relative path conventionally holds a Jx document. Kept in step with
  * monaco-setup.ts's DOCUMENT_FILE_MATCH so the assistant's gate and the editor's diagnostics cover
@@ -170,7 +142,7 @@ export function registerProjectTools(
         const { dir } = args as { dir?: string };
         const start = dir === undefined || dir === "" ? "." : normalizeRelPath(dir);
         if (start === null) {
-          return pathError(dir);
+          return invalidPathResult(dir);
         }
         const platform = getPlatform();
         const entries: { path: string; type: string; size?: number }[] = [];
@@ -234,7 +206,7 @@ export function registerProjectTools(
       async execute(args) {
         const relPath = normalizeRelPath((args as { path: string }).path);
         if (relPath === null) {
-          return pathError((args as { path: string }).path);
+          return invalidPathResult((args as { path: string }).path);
         }
         try {
           const content = await getPlatform().readFile(relPath);
@@ -282,11 +254,11 @@ export function registerProjectTools(
         },
         required: ["path", "content"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const { path, content } = args as { path: string; content: string };
         const relPath = normalizeRelPath(path);
         if (relPath === null) {
-          return pathError(path);
+          return invalidPathResult(path);
         }
         if (content.length > WRITE_CAP_BYTES) {
           return {
@@ -389,11 +361,17 @@ export function registerProjectTools(
           await getPlatform().writeFile(relPath, content);
           /* Disk, not transaction: there is no undo behind this and there never was. Recorded as
              `disk: true` so the panel can say so to the person holding ⌘Z — the caveat used to be
-             appended to the model-facing summary only (§7.4). */
-          recordWrite({ disk: true, ok: true, path: relPath, tool: "write_file" });
+             appended to the model-facing summary only (`ai.md` §3.2). */
+          ctx.ledger.record({ disk: true, ok: true, path: relPath, tool: "write_file" });
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          recordWrite({ disk: true, error: message, ok: false, path: relPath, tool: "write_file" });
+          ctx.ledger.record({
+            disk: true,
+            error: message,
+            ok: false,
+            path: relPath,
+            tool: "write_file",
+          });
           return {
             success: false,
             error: `Failed to write "${relPath}": ${message}`,
@@ -511,7 +489,7 @@ export function registerProjectTools(
         },
         required: ["name"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const {
           name,
           description,
@@ -598,6 +576,10 @@ export function registerProjectTools(
             error: `Failed to create project: ${error instanceof Error ? error.message : String(error)}`,
           };
         }
+        /* The project is on disk from here, whether or not this window goes on to open it, and no
+           undo reaches it. Recorded, it is what the turn changed: without it a turn that bootstrapped
+           a project and then only read reported that it had applied nothing. */
+        ctx.ledger.record({ disk: true, ok: true, path: result.root, tool: "create_project" });
 
         /*
          * Git init, then the full project-open flow, then a check that it landed — all three in