@moxxy/plugin-self-update 0.26.0

package/src/classify.ts

@@ -0,0 +1,221 @@
+import type { EventLogReader } from '@moxxy/sdk';
+
+/**
+ * Request classification for self-update. The *signals* are gathered
+ * deterministically here; the *decision* is advisory — the orchestrating
+ * skill makes the final call. This keeps mechanical inspection in code and
+ * judgement in the prompt (mirroring how self-improver splits the two).
+ */
+
+export type Tier = 'skill' | 'plugin' | 'core';
+
+export interface ClassifyInput {
+  readonly trigger: 'error' | 'request';
+  readonly text?: string;
+}
+
+export interface ClassifySignals {
+  readonly failedTools: ReadonlyArray<string>;
+  readonly errorMessages: ReadonlyArray<string>;
+  readonly registeredTools: ReadonlyArray<string>;
+}
+
+export interface ClassifyResult {
+  readonly tier: Tier;
+  readonly candidateName?: string;
+  readonly evidence: ReadonlyArray<string>;
+  readonly rationale: string;
+}
+
+const CORE_HINTS = [
+  '@moxxy/core',
+  'packages/core',
+  'core/src',
+  'run-turn',
+  'session.ts',
+  'event log',
+  'new event type',
+  'loop strategy internals',
+  'registry internals',
+];
+
+const SKILL_HINTS = [
+  'always',
+  'whenever',
+  'every time',
+  'remember to',
+  'before you',
+  'workflow',
+  'procedure',
+  'instruction',
+];
+
+const PLUGIN_HINTS = [
+  'add a tool',
+  'new tool',
+  'integrate',
+  'integration',
+  'connect to',
+  'call the',
+  ' api',
+  'command that',
+  'wrap',
+  'override',
+];
+
+/** Gather deterministic signals from the session event log. */
+export function gatherSignals(
+  log: EventLogReader,
+  registeredTools: ReadonlyArray<string>,
+  lookback = 40,
+): ClassifySignals {
+  const callNames = new Map<string, string>();
+  for (const e of log.ofType('tool_call_requested')) {
+    callNames.set(String(e.callId), e.name);
+  }
+  const recent = log.slice(Math.max(0, log.length - lookback));
+  const failedTools = new Set<string>();
+  const errorMessages: string[] = [];
+  for (const e of recent) {
+    if (e.type === 'tool_result' && !e.ok) {
+      const name = callNames.get(String(e.callId));
+      if (name) failedTools.add(name);
+      if (e.error?.message) errorMessages.push(e.error.message);
+    } else if (e.type === 'error') {
+      errorMessages.push(e.message);
+    }
+  }
+  return {
+    failedTools: [...failedTools],
+    errorMessages,
+    registeredTools,
+  };
+}
+
+function includesAny(haystack: string, needles: ReadonlyArray<string>): string | null {
+  const lower = haystack.toLowerCase();
+  for (const n of needles) {
+    if (lower.includes(n)) return n;
+  }
+  return null;
+}
+
+/** Suggest a kebab-case artifact name from free text. */
+export function suggestName(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length > 2 && !STOP_WORDS.has(w))
+    .slice(0, 4);
+  return words.length > 0 ? words.join('-') : undefined;
+}
+
+const STOP_WORDS = new Set([
+  'the',
+  'and',
+  'for',
+  'add',
+  'can',
+  'you',
+  'please',
+  'that',
+  'this',
+  'with',
+  'make',
+  'create',
+  'want',
+  'would',
+  'like',
+  'your',
+]);
+
+/**
+ * Decide the lowest-risk tier that can satisfy the request, plus the evidence
+ * behind that suggestion. Always advisory.
+ */
+export function classify(input: ClassifyInput, signals: ClassifySignals): ClassifyResult {
+  const evidence: string[] = [];
+  const blob = `${input.text ?? ''} ${signals.errorMessages.join(' ')}`;
+
+  const coreHit = includesAny(blob, CORE_HINTS);
+  if (coreHit) {
+    evidence.push(`mentions core internals ("${coreHit}")`);
+    return {
+      tier: 'core',
+      evidence,
+      rationale:
+        'The change appears to touch @moxxy/core internals — escalate to a Tier-2 core patch (build + overlay + restart). Confirm a plugin override cannot express it first.',
+    };
+  }
+
+  // A referenced-but-unregistered capability ⇒ a new plugin/tool is needed.
+  const missing = signals.failedTools.filter((t) => !signals.registeredTools.includes(t));
+  if (missing.length > 0) {
+    evidence.push(`failed call to unregistered tool(s): ${missing.join(', ')}`);
+    return {
+      tier: 'plugin',
+      candidateName: suggestName(input.text) ?? missing[0],
+      evidence,
+      rationale:
+        'A capability is missing. Author a new plugin (or install a published one) that provides the tool, then hot-reload.',
+    };
+  }
+
+  // An existing tool misbehaved ⇒ usually instructions (skill) or a hook wrapper.
+  if (signals.failedTools.length > 0) {
+    evidence.push(`registered tool(s) misbehaved: ${signals.failedTools.join(', ')}`);
+    const pluginHit = includesAny(blob, PLUGIN_HINTS);
+    if (pluginHit) {
+      evidence.push(`request implies a behavior override ("${pluginHit}")`);
+      return {
+        tier: 'plugin',
+        candidateName: suggestName(input.text),
+        evidence,
+        rationale:
+          'An existing tool misbehaves and the fix is a behavior change — wrap it in a plugin (onToolResult / onToolCall) rather than editing core.',
+      };
+    }
+    return {
+      tier: 'skill',
+      candidateName: suggestName(input.text),
+      evidence,
+      rationale:
+        'The tool exists but was used wrongly — a skill that encodes the correct procedure is the lowest-risk fix.',
+    };
+  }
+
+  // No error signal: classify the free-text request.
+  const skillHit = includesAny(blob, SKILL_HINTS);
+  const pluginHit = includesAny(blob, PLUGIN_HINTS);
+  if (pluginHit && !skillHit) {
+    evidence.push(`request implies a new capability ("${pluginHit}")`);
+    return {
+      tier: 'plugin',
+      candidateName: suggestName(input.text),
+      evidence,
+      rationale: 'The request asks for a new action/capability — author a plugin tool and hot-reload.',
+    };
+  }
+  if (skillHit) {
+    evidence.push(`request describes a procedure ("${skillHit}")`);
+    return {
+      tier: 'skill',
+      candidateName: suggestName(input.text),
+      evidence,
+      rationale: 'The request is a recurring procedure expressible with existing tools — author a skill.',
+    };
+  }
+
+  // Default for an unqualified "add XYZ": prefer a plugin (capability), the
+  // common case, but the skill should reconsider a skill if no code is needed.
+  evidence.push('no strong signal; defaulting to the plugin tier');
+  return {
+    tier: 'plugin',
+    candidateName: suggestName(input.text),
+    evidence,
+    rationale:
+      'Ambiguous request. Default to authoring a plugin; if the change needs no new code (only instructions), drop to the skill tier instead.',
+  };
+}

package/src/core-tools/apply.ts

@@ -0,0 +1,44 @@
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { overlayPackages, readCoreJournal, restoreOverlay, writeCoreJournal } from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import { resolveCore, snapshotDir, type CoreToolDeps } from './shared.js';
+
+// ── self_update_core_apply ──────────────────────────────────────────────────
+export function coreApplyTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_apply',
+    description:
+      'Overlay the verified build into the live global install (snapshotting the previous dist for rollback) and stage a restart. The new core code only activates after moxxy restarts. Requires a prior successful self_update_core_verify.',
+    inputSchema: z.object({ coreTxnId: z.string().min(1) }),
+    permission: { action: 'prompt' },
+    handler: async (input, ctx: ToolContext) => {
+      const journal = await readCoreJournal(deps.moxxyDir, input.coreTxnId);
+      if (journal.state !== 'verified') {
+        throw new Error(`core txn ${input.coreTxnId} is "${journal.state}", not "verified" — run self_update_core_verify first`);
+      }
+      const install = resolveCore(cd);
+      if (!install) throw new Error('could not resolve @moxxy/core');
+      const res = await overlayPackages({
+        repo: journal.repoDir,
+        install,
+        pkgNames: journal.packages,
+        snapshotDir: snapshotDir(deps.moxxyDir, input.coreTxnId),
+      });
+      if (!res.ok) {
+        await restoreOverlay({ install, pkgNames: journal.packages, snapshotDir: snapshotDir(deps.moxxyDir, input.coreTxnId) }).catch(() => undefined);
+        throw new Error(`overlay failed and was rolled back: ${res.message}`);
+      }
+      journal.state = 'staged_restart';
+      await writeCoreJournal(deps.moxxyDir, journal);
+      await emitSafe(deps, ctx, 'core_apply', { txnId: input.coreTxnId, applied: res.applied });
+      return {
+        ok: true,
+        applied: res.applied,
+        restartRequired: true,
+        message:
+          'Core patch overlaid. RESTART moxxy to activate it (re-run `moxxy`, or it restarts on the next launch under a supervisor). It will be committed automatically on a clean boot; use self_update_core_rollback if needed.',
+      };
+    },
+  });
+}

package/src/core-tools/begin.ts

@@ -0,0 +1,94 @@
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import {
+  corePreflight,
+  countCorruptCoreTxns,
+  listCoreTxns,
+  newCoreTxnId,
+  provisionWorkspace,
+  writeCoreJournal,
+  type CoreJournal,
+} from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import { resolveCore, type CoreToolDeps } from './shared.js';
+
+// ── self_update_core_begin ──────────────────────────────────────────────────
+export function coreBeginTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_begin',
+    description:
+      'Start a Tier-2 core patch: provision a source clone pinned to the EXACT installed commit (git clone/fetch + checkout gitHead + pnpm install — this can take minutes) and open a transaction. Returns a coreTxnId and the repo path. Edit files ONLY via self_update_core_write / self_update_core_edit, then self_update_core_verify. Prefer a Tier-1 plugin override first — only patch core when truly unavoidable.',
+    inputSchema: z.object({
+      packages: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Affected @moxxy/* package names, e.g. ["@moxxy/core"].'),
+    }),
+    permission: { action: 'prompt' },
+    handler: async (input, ctx: ToolContext) => {
+      const install = resolveCore(cd);
+      if (!install) throw new Error('could not resolve the installed @moxxy/core — cannot self-update core');
+
+      // Fail CLOSED on a corrupt journal: an unparseable in-flight journal would
+      // otherwise vanish from listCoreTxns and let this begin clobber the shared
+      // repoDir. Refuse rather than risk concurrent overlay corruption.
+      const corrupt = await countCorruptCoreTxns(deps.moxxyDir);
+      if (corrupt > 0) {
+        throw new Error(
+          `${corrupt} core-update transaction journal(s) are corrupt/unreadable — refusing to start a ` +
+            `new core update (the serialization guard can't see them). Inspect ` +
+            `~/.moxxy/self-update/core-txns and resolve them before retrying.`,
+        );
+      }
+      // Serialize core transactions: only ONE may be in flight at a time. Every
+      // txn shares the single provisioned workspace (repoDir), so a second
+      // concurrent txn would clobber the first's edits + build. Refuse rather
+      // than corrupt — the active txn must be finished (verify → commit) or
+      // released (self_update_core_rollback, which is a no-op overlay restore +
+      // marks it rolled_back even when nothing was applied yet).
+      const active = (await listCoreTxns(deps.moxxyDir)).find(
+        (j) => j.state !== 'committed' && j.state !== 'rolled_back',
+      );
+      if (active) {
+        throw new Error(
+          `a core update is already in progress (txn ${active.txnId}, state "${active.state}"). ` +
+            `Finish it (self_update_core_verify → self_update_commit) or release it with ` +
+            `self_update_core_rollback({ coreTxnId: "${active.txnId}" }) before starting another.`,
+        );
+      }
+
+      const pf = await corePreflight(install);
+      if (!pf.ok) {
+        throw new Error(
+          `core update preflight failed: ${pf.checks.filter((c) => !c.ok).map((c) => `${c.id} (${c.detail})`).join('; ')}`,
+        );
+      }
+      const prov = await provisionWorkspace({
+        moxxyDir: deps.moxxyDir,
+        install,
+        ...(deps.coreUpdate?.repoUrlOverride ? { repoUrlOverride: deps.coreUpdate.repoUrlOverride } : {}),
+      });
+      if (!prov.ok) throw new Error(`provisioning failed (escalate to the user): ${prov.message}`);
+
+      const txnId = newCoreTxnId();
+      const journal: CoreJournal = {
+        txnId,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        packages: [...input.packages],
+        version: install.version,
+        ...(install.gitHead ? { gitHead: install.gitHead } : {}),
+        repoDir: prov.repoDir,
+        state: 'provisioned',
+        attempts: [],
+      };
+      await writeCoreJournal(deps.moxxyDir, journal);
+      await emitSafe(deps, ctx, 'core_begin', { txnId, packages: journal.packages, version: install.version });
+      return {
+        coreTxnId: txnId,
+        repoDir: prov.repoDir,
+        next: 'Edit files under the repo with self_update_core_write / self_update_core_edit (paths relative to the repo), then call self_update_core_verify.',
+      };
+    },
+  });
+}

package/src/core-tools/edit.ts

@@ -0,0 +1,33 @@
+import { promises as fs } from 'node:fs';
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { readCoreJournal, safeRepoPath } from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import type { CoreToolDeps } from './shared.js';
+
+// ── self_update_core_edit ───────────────────────────────────────────────────
+export function coreEditTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_edit',
+    description:
+      'Find-and-replace a unique string in a file inside the provisioned core clone (path relative to the repo root). Approval-gated.',
+    inputSchema: z.object({
+      coreTxnId: z.string().min(1),
+      file: z.string().min(1),
+      oldString: z.string().min(1),
+      newString: z.string(),
+    }),
+    permission: { action: 'prompt' },
+    handler: async (input, ctx: ToolContext) => {
+      const journal = await readCoreJournal(deps.moxxyDir, input.coreTxnId);
+      const abs = safeRepoPath(journal.repoDir, input.file);
+      const cur = await fs.readFile(abs, 'utf8');
+      const count = cur.split(input.oldString).length - 1;
+      if (count === 0) throw new Error(`oldString not found in ${input.file}`);
+      if (count > 1) throw new Error(`oldString is not unique in ${input.file} (${count} matches)`);
+      await fs.writeFile(abs, cur.replace(input.oldString, input.newString), 'utf8');
+      await emitSafe(deps, ctx, 'core_edit', { txnId: input.coreTxnId, file: input.file });
+      return { ok: true, edited: input.file };
+    },
+  });
+}

package/src/core-tools/index.ts

@@ -0,0 +1,33 @@
+import type { ToolDef } from '@moxxy/sdk';
+import type { SelfUpdateDeps } from '../deps.js';
+import { coreApplyTool } from './apply.js';
+import { coreBeginTool } from './begin.js';
+import { coreEditTool } from './edit.js';
+import { corePreflightTool } from './preflight.js';
+import { coreRollbackTool } from './rollback.js';
+import type { CoreToolDeps } from './shared.js';
+import { coreStatusTool } from './status.js';
+import { coreVerifyTool } from './verify.js';
+import { coreWriteTool } from './write.js';
+
+export type { CoreToolDeps } from './shared.js';
+
+/**
+ * Composes the Tier-2 core-update tools from per-tool factories (mirroring the
+ * Tier-1 layout). `fromUrl` is the module URL used to resolve the live
+ * `@moxxy/core` install (the plugin entry's `import.meta.url`). Order preserved
+ * exactly as before extraction.
+ */
+export function coreTools(deps: SelfUpdateDeps, fromUrl: string): ToolDef[] {
+  const cd: CoreToolDeps = { deps, fromUrl };
+  return [
+    corePreflightTool(cd),
+    coreBeginTool(cd),
+    coreWriteTool(cd),
+    coreEditTool(cd),
+    coreVerifyTool(cd),
+    coreApplyTool(cd),
+    coreRollbackTool(cd),
+    coreStatusTool(cd),
+  ];
+}

package/src/core-tools/preflight.ts

@@ -0,0 +1,15 @@
+import { defineTool, z, type ToolDef } from '@moxxy/sdk';
+import { corePreflight } from '../core-update.js';
+import { resolveCore, type CoreToolDeps } from './shared.js';
+
+// ── self_update_core_preflight ──────────────────────────────────────────────
+export function corePreflightTool(cd: CoreToolDeps): ToolDef {
+  return defineTool({
+    name: 'self_update_core_preflight',
+    description:
+      'Read-only. Check whether a Tier-2 core patch is even possible: git + pnpm present, @moxxy/core resolvable, a pinned source commit (gitHead) and repo URL in its published metadata. Run this BEFORE attempting to patch @moxxy/core; if any check fails, do not start — tell the user.',
+    inputSchema: z.object({}),
+    permission: { action: 'allow' },
+    handler: async () => corePreflight(resolveCore(cd)),
+  });
+}

package/src/core-tools/rollback.ts

@@ -0,0 +1,30 @@
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { gcCoreTxns, readCoreJournal, restoreOverlay, writeCoreJournal } from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import { resolveCore, snapshotDir, type CoreToolDeps } from './shared.js';
+
+// ── self_update_core_rollback ───────────────────────────────────────────────
+export function coreRollbackTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_rollback',
+    description:
+      'Undo a core overlay: restore the previous dist from the snapshot. A restart is required to drop the patched code. Use if a core patch built+loaded but misbehaves.',
+    inputSchema: z.object({ coreTxnId: z.string().min(1), reason: z.string().optional() }),
+    permission: { action: 'allow' },
+    handler: async (input, ctx: ToolContext) => {
+      const journal = await readCoreJournal(deps.moxxyDir, input.coreTxnId);
+      const install = resolveCore(cd);
+      if (!install) throw new Error('could not resolve @moxxy/core');
+      await restoreOverlay({ install, pkgNames: journal.packages, snapshotDir: snapshotDir(deps.moxxyDir, input.coreTxnId) });
+      journal.state = 'rolled_back';
+      await writeCoreJournal(deps.moxxyDir, journal);
+      await emitSafe(deps, ctx, 'core_rollback', { txnId: input.coreTxnId, reason: input.reason ?? null });
+      // Reclaim disk now: this txn is terminal, and its (large) dist snapshot is
+      // no longer needed. Prune older terminal core txns too. Best-effort — keep
+      // the freshly-rolled-back one + recent history. Mirrors maxTxnRetained.
+      await gcCoreTxns(deps.moxxyDir, deps.maxTxnRetained ?? 5).catch(() => undefined);
+      return { ok: true, restored: journal.packages, restartRequired: true };
+    },
+  });
+}

package/src/core-tools/shared.test.ts

@@ -0,0 +1,16 @@
+import * as path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { coreTxnDir } from '../core-update.js';
+import { snapshotDir } from './shared.js';
+
+describe('core-tools shared helpers', () => {
+  it('snapshotDir nests "snapshot" under the txn dir', () => {
+    const moxxyDir = '/tmp/.moxxy';
+    const txnId = 'core-abc123';
+    expect(snapshotDir(moxxyDir, txnId)).toBe(path.join(coreTxnDir(moxxyDir, txnId), 'snapshot'));
+  });
+
+  it('produces distinct snapshot dirs for distinct txns', () => {
+    expect(snapshotDir('/x', 'a')).not.toBe(snapshotDir('/x', 'b'));
+  });
+});

package/src/core-tools/shared.ts

@@ -0,0 +1,24 @@
+import * as path from 'node:path';
+import { coreTxnDir } from '../core-update.js';
+import { resolveCoreInstall, type SelfUpdateDeps } from '../deps.js';
+import type { CoreInstallInfo } from '../core-update.js';
+
+/**
+ * Context threaded into every Tier-2 core-tool factory. `fromUrl` is the
+ * module URL used to resolve the live `@moxxy/core` install (defaults to the
+ * plugin entry's `import.meta.url`, overridable via deps.coreUpdate.fromUrl).
+ */
+export interface CoreToolDeps {
+  readonly deps: SelfUpdateDeps;
+  readonly fromUrl: string;
+}
+
+/** Where a given core transaction parks its pre-overlay dist snapshot. */
+export function snapshotDir(moxxyDir: string, txnId: string): string {
+  return path.join(coreTxnDir(moxxyDir, txnId), 'snapshot');
+}
+
+/** Resolve the live `@moxxy/core` install for this plugin's deps. */
+export function resolveCore(c: CoreToolDeps): CoreInstallInfo | null {
+  return resolveCoreInstall(c.deps, c.fromUrl);
+}

package/src/core-tools/status.ts

@@ -0,0 +1,26 @@
+import { defineTool, z, type ToolDef } from '@moxxy/sdk';
+import { listCoreTxns } from '../core-update.js';
+import type { CoreToolDeps } from './shared.js';
+
+// ── self_update_core_status ─────────────────────────────────────────────────
+export function coreStatusTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_status',
+    description: 'List Tier-2 core-update transactions and their state.',
+    inputSchema: z.object({}),
+    permission: { action: 'allow' },
+    handler: async () => {
+      const all = await listCoreTxns(deps.moxxyDir);
+      return {
+        transactions: all.map((j) => ({
+          coreTxnId: j.txnId,
+          state: j.state,
+          packages: j.packages,
+          version: j.version,
+          updatedAt: j.updatedAt,
+        })),
+      };
+    },
+  });
+}

package/src/core-tools/verify.ts

@@ -0,0 +1,39 @@
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { readCoreJournal, verifyCorePackages, writeCoreJournal } from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import { resolveCore, type CoreToolDeps } from './shared.js';
+
+// ── self_update_core_verify ─────────────────────────────────────────────────
+export function coreVerifyTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_verify',
+    description:
+      'Build, typecheck and test the affected core packages (and their dependents) in the clone, and confirm the patch adds no new runtime dependency. Returns stage results. Run AFTER edits; nothing in the live install changes here.',
+    inputSchema: z.object({ coreTxnId: z.string().min(1) }),
+    permission: { action: 'prompt' },
+    handler: async (input, ctx: ToolContext) => {
+      const journal = await readCoreJournal(deps.moxxyDir, input.coreTxnId);
+      const install = resolveCore(cd);
+      if (!install) throw new Error('could not resolve @moxxy/core');
+      const res = await verifyCorePackages(journal.repoDir, install, journal.packages);
+      journal.attempts.push({
+        at: new Date().toISOString(),
+        stage: 'verify',
+        ok: res.ok,
+        message: res.ok ? 'build/typecheck/test ok' : res.stages.find((s) => !s.ok)?.message ?? 'failed',
+      });
+      journal.state = res.ok ? 'verified' : journal.state;
+      await writeCoreJournal(deps.moxxyDir, journal);
+      await emitSafe(deps, ctx, res.ok ? 'core_verify_ok' : 'core_verify_failed', { txnId: input.coreTxnId });
+      return {
+        ok: res.ok,
+        stages: res.stages,
+        newDeps: res.newDeps,
+        next: res.ok
+          ? 'Passed — call self_update_core_apply to overlay it into the live install (a restart is then required).'
+          : 'Fix the errors and re-verify, or escalate to the user.',
+      };
+    },
+  });
+}

package/src/core-tools/write.ts

@@ -0,0 +1,30 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { defineTool, z, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { readCoreJournal, safeRepoPath } from '../core-update.js';
+import { emitSafe } from '../deps.js';
+import type { CoreToolDeps } from './shared.js';
+
+// ── self_update_core_write ──────────────────────────────────────────────────
+export function coreWriteTool(cd: CoreToolDeps): ToolDef {
+  const { deps } = cd;
+  return defineTool({
+    name: 'self_update_core_write',
+    description:
+      'Write a file inside the provisioned core clone for a transaction (paths are relative to the repo root and cannot escape it). This is an approval-gated code write — show the user the content first.',
+    inputSchema: z.object({
+      coreTxnId: z.string().min(1),
+      file: z.string().min(1).describe('Path relative to the repo root, e.g. packages/core/src/foo.ts'),
+      content: z.string(),
+    }),
+    permission: { action: 'prompt' },
+    handler: async (input, ctx: ToolContext) => {
+      const journal = await readCoreJournal(deps.moxxyDir, input.coreTxnId);
+      const abs = safeRepoPath(journal.repoDir, input.file);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, input.content, 'utf8');
+      await emitSafe(deps, ctx, 'core_write', { txnId: input.coreTxnId, file: input.file });
+      return { ok: true, wrote: input.file };
+    },
+  });
+}