@corenel/harness 0.1.0 → 0.3.2

package/dist/snapshot/manifest.js

@@ -0,0 +1,141 @@
+export const SNAPSHOT_VERSION = 1;
+/**
+ * Strip anything that looks like a secret VALUE from provider config.
+ *
+ * Defense in depth, not a substitute for callers behaving: provider settings are
+ * a loose bag, and a snapshot is a thing people mail around. A key that survives
+ * into a manifest is a key in someone's git history. Keys are matched by name
+ * because that is the only signal available in an untyped record.
+ */
+const SECRET_WORD = /(^|_)(key|secret|token|password|passwd|credential|credentials|authorization|auth|bearer|apikey)($|_)/;
+/**
+ * Normalize a key so camelCase reads like snake_case before matching.
+ *
+ * Without this, `apiKey` — the single most common spelling of the thing this
+ * function exists to catch — sailed straight through, because `key` was not
+ * preceded by a separator. Both boundaries are needed: lower-to-upper for
+ * `apiKey`, and the caps-run split for `APIKey`.
+ */
+function normalizeKey(key) {
+    return key
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/-/g, '_')
+        .toLowerCase();
+}
+function isSecretKey(key) {
+    return SECRET_WORD.test(normalizeKey(key));
+}
+export function redactProvider(provider) {
+    if (!provider)
+        return null;
+    const out = {};
+    for (const key of Object.keys(provider).sort()) {
+        if (isSecretKey(key))
+            continue;
+        const v = provider[key];
+        // Nested objects get the same treatment; anything else is copied as-is.
+        out[key] = (typeof v === 'object' && v !== null && !Array.isArray(v))
+            ? redactProvider(v)
+            : v;
+    }
+    return out;
+}
+export function buildManifest(input) {
+    return {
+        snapshotVersion: SNAPSHOT_VERSION,
+        sessionId: input.sessionId,
+        // Unbranched sessions are their own lineage root, which is the common case
+        // and must not require every caller to think about it.
+        lineageRoot: input.lineageRoot ?? input.sessionId,
+        parent: input.parent ?? null,
+        createdAt: input.createdAt,
+        baseImage: input.baseImage ?? null,
+        policy: input.policy ?? null,
+        lock: input.lock ?? null,
+        provider: redactProvider(input.provider),
+        // Names only, deduped and sorted so the manifest is stable.
+        env: [...new Set(input.env ?? [])].sort(),
+        tree: input.tree,
+    };
+}
+/** Canonical text form: fixed key order, sorted env, trailing newline. */
+export function serializeManifest(m) {
+    const canonical = {
+        snapshotVersion: SNAPSHOT_VERSION,
+        sessionId: m.sessionId,
+        lineageRoot: m.lineageRoot || m.sessionId,
+        parent: m.parent,
+        createdAt: m.createdAt,
+        baseImage: m.baseImage,
+        policy: m.policy ?? null,
+        lock: m.lock ?? null,
+        provider: m.provider ?? null,
+        env: [...new Set(m.env)].sort(),
+        tree: m.tree,
+    };
+    return JSON.stringify(canonical, null, 2) + '\n';
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse a manifest, or null when the text is not one.
+ *
+ * Strict about identity (`sessionId`, `tree`) because a snapshot that cannot say
+ * what it is or what it contains is unusable. A future `snapshotVersion` is
+ * rejected rather than read under rules that no longer apply — the same call the
+ * lockfile makes, for the same reason.
+ */
+export function parseManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed.snapshotVersion !== SNAPSHOT_VERSION)
+        return null;
+    if (typeof parsed.sessionId !== 'string' || !parsed.sessionId)
+        return null;
+    if (typeof parsed.tree !== 'string' || !parsed.tree)
+        return null;
+    return {
+        snapshotVersion: SNAPSHOT_VERSION,
+        sessionId: parsed.sessionId,
+        // An older manifest has no lineage root; it was written before branching
+        // existed, so it IS its own root.
+        lineageRoot: typeof parsed.lineageRoot === 'string' && parsed.lineageRoot ? parsed.lineageRoot : parsed.sessionId,
+        parent: typeof parsed.parent === 'string' ? parsed.parent : null,
+        createdAt: typeof parsed.createdAt === 'number' ? parsed.createdAt : 0,
+        baseImage: typeof parsed.baseImage === 'string' ? parsed.baseImage : null,
+        policy: parsed.policy ?? null,
+        lock: (parsed.lock ?? null),
+        provider: isRecord(parsed.provider) ? parsed.provider : null,
+        env: Array.isArray(parsed.env) ? [...new Set(parsed.env.filter((e) => typeof e === 'string'))].sort() : [],
+        tree: parsed.tree,
+    };
+}
+/**
+ * Is this manifest safe to rehydrate from?
+ *
+ * A snapshot with no policy would restore UNGOVERNED. Rather than defaulting to
+ * something permissive — or to something strict the user did not choose — this
+ * refuses, and the caller decides whether to attach a policy explicitly. Silence
+ * here is how an audit trail ends up describing a run nobody authorized.
+ */
+export function manifestProblems(m) {
+    const problems = [];
+    if (m.policy === null || m.policy === undefined) {
+        problems.push('no policy — restoring would run ungoverned (see spec s5.1)');
+    }
+    if (!m.tree)
+        problems.push('no tree hash — the snapshot does not say what it contains');
+    if (!m.sessionId)
+        problems.push('no session id');
+    return problems;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/snapshot/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../snapshot/manifest.ts"],"names":[],"mappings":"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"}

package/dist/snapshot/tree.d.ts

@@ -0,0 +1,62 @@
+/** path -> content hash. Sorted on serialize, so the same tree is the same text. */
+export type Tree = Record<string, string>;
+export interface TreeDelta {
+    /** Paths present now and absent from the parent. */
+    added: string[];
+    /** Paths in both, with different content. */
+    modified: string[];
+    /** Paths in the parent and gone now. A snapshot that cannot express deletion
+     * silently resurrects files on restore. */
+    removed: string[];
+}
+/** Canonical text form of a tree — sorted paths, trailing newline. */
+export declare function serializeTree(tree: Tree): string;
+export declare function parseTree(text: string): Tree | null;
+/** What changed between two trees. Deterministic: every list is sorted. */
+export declare function diffTrees(parent: Tree, current: Tree): TreeDelta;
+/** True when nothing changed — worth checking before writing a snapshot nobody
+ * needs, and before shipping bytes across a wire. */
+export declare function isEmptyDelta(d: TreeDelta): boolean;
+/**
+ * The blob hashes a delta actually needs shipped.
+ *
+ * DEDUPED, which is the point of content addressing: two paths with identical
+ * content share one blob, so a copied file or a repeated boilerplate header costs
+ * nothing extra. Removals need no blob at all.
+ */
+export declare function blobsForDelta(delta: TreeDelta, current: Tree): string[];
+/**
+ * Apply a delta to a parent tree, producing the child tree.
+ *
+ * The inverse of diffTrees, and the restore path's core step. `hashes` supplies
+ * the content hash for every added/modified path — a delta alone does not carry
+ * them, because the tree it came from already did.
+ */
+export declare function applyDelta(parent: Tree, delta: TreeDelta, hashes: Tree): Tree;
+/**
+ * Collapse a lineage into one effective tree.
+ *
+ * `chain` runs oldest-first: a full snapshot's tree, then each descendant's
+ * delta. Restoring walks it forward rather than resolving parents recursively at
+ * read time, so a long chain costs one pass.
+ */
+export declare function collapseChain(base: Tree, steps: readonly {
+    delta: TreeDelta;
+    hashes: Tree;
+}[]): Tree;
+/** Paths in a tree whose blobs are absent from `have` — what a restore must
+ * fetch before it can write anything. */
+export declare function missingBlobs(tree: Tree, have: ReadonlySet<string>): string[];
+/**
+ * Paths a snapshot must NOT capture.
+ *
+ * Session and run logs are Layer 3 and travel by reference (spec s4), so
+ * capturing them here would duplicate them and, worse, let a stale copy overwrite
+ * the live append-only log on restore — the exact clobber the single-writer rule
+ * exists to prevent. Blobs are the session's own offloaded outputs, referenced
+ * the same way.
+ */
+export declare function isLayer3Path(path: string, stateDir: string): boolean;
+/** Drop Layer 3 paths from a tree before diffing it. */
+export declare function withoutLayer3(tree: Tree, stateDir: string): Tree;
+//# sourceMappingURL=tree.d.ts.map

package/dist/snapshot/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../snapshot/tree.ts"],"names":[],"mappings":"AAiBA,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;+CAC2C;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAKhD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CASnD;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,SAAS,CAahE;AAED;qDACqD;AACrD,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,EAAE,CAOvE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,CAW7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,EAAE,GAAG,IAAI,CAEpG;AAED;yCACyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpE;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMhE"}

package/dist/snapshot/tree.js

@@ -0,0 +1,147 @@
+/* Snapshot Layer 2 — the content-addressed file tree and the delta between two.
+ *
+ * A snapshot ships a DIFF, not a disk image. Spec s4: a raw microVM memory dump
+ * does not move between an Apple Silicon laptop and a Linux host, but a file diff
+ * does, and because the base is pinned by digest both ends provably start from
+ * identical ground. Typically megabytes, not gigabytes.
+ *
+ * This module is pure — no I/O, no crypto, no node. Hashing is the caller's
+ * (node:crypto server-side, SubtleCrypto in a browser), which is also what keeps
+ * one implementation serving both.
+ *
+ * It also gives `parent` a job. An earlier review flagged the manifest's lineage
+ * field as unused and asked whether to cut it; incremental snapshots are the use.
+ * The first snapshot of a session is full; each later one records only what
+ * changed since its parent, and a restore walks the chain back to a full one.
+ */
+/** Canonical text form of a tree — sorted paths, trailing newline. */
+export function serializeTree(tree) {
+    const keys = Object.keys(tree).sort();
+    const out = {};
+    for (const k of keys)
+        out[k] = tree[k];
+    return JSON.stringify(out, null, 2) + '\n';
+}
+export function parseTree(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === 'string' && v)
+            out[k] = v;
+    }
+    return out;
+}
+/** What changed between two trees. Deterministic: every list is sorted. */
+export function diffTrees(parent, current) {
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const [path, hash] of Object.entries(current)) {
+        const before = parent[path];
+        if (before === undefined)
+            added.push(path);
+        else if (before !== hash)
+            modified.push(path);
+    }
+    for (const path of Object.keys(parent)) {
+        if (current[path] === undefined)
+            removed.push(path);
+    }
+    return { added: added.sort(), modified: modified.sort(), removed: removed.sort() };
+}
+/** True when nothing changed — worth checking before writing a snapshot nobody
+ * needs, and before shipping bytes across a wire. */
+export function isEmptyDelta(d) {
+    return d.added.length === 0 && d.modified.length === 0 && d.removed.length === 0;
+}
+/**
+ * The blob hashes a delta actually needs shipped.
+ *
+ * DEDUPED, which is the point of content addressing: two paths with identical
+ * content share one blob, so a copied file or a repeated boilerplate header costs
+ * nothing extra. Removals need no blob at all.
+ */
+export function blobsForDelta(delta, current) {
+    const needed = new Set();
+    for (const path of [...delta.added, ...delta.modified]) {
+        const hash = current[path];
+        if (hash)
+            needed.add(hash);
+    }
+    return [...needed].sort();
+}
+/**
+ * Apply a delta to a parent tree, producing the child tree.
+ *
+ * The inverse of diffTrees, and the restore path's core step. `hashes` supplies
+ * the content hash for every added/modified path — a delta alone does not carry
+ * them, because the tree it came from already did.
+ */
+export function applyDelta(parent, delta, hashes) {
+    const out = { ...parent };
+    for (const path of delta.removed)
+        delete out[path];
+    for (const path of [...delta.added, ...delta.modified]) {
+        const hash = hashes[path];
+        // A delta naming a path with no hash is corrupt; skipping it would silently
+        // produce a tree that does not match the snapshot's own tree hash, which the
+        // caller can then detect. Better a detectable mismatch than invented content.
+        if (hash)
+            out[path] = hash;
+    }
+    return out;
+}
+/**
+ * Collapse a lineage into one effective tree.
+ *
+ * `chain` runs oldest-first: a full snapshot's tree, then each descendant's
+ * delta. Restoring walks it forward rather than resolving parents recursively at
+ * read time, so a long chain costs one pass.
+ */
+export function collapseChain(base, steps) {
+    return steps.reduce((acc, step) => applyDelta(acc, step.delta, step.hashes), { ...base });
+}
+/** Paths in a tree whose blobs are absent from `have` — what a restore must
+ * fetch before it can write anything. */
+export function missingBlobs(tree, have) {
+    const missing = new Set();
+    for (const hash of Object.values(tree)) {
+        if (!have.has(hash))
+            missing.add(hash);
+    }
+    return [...missing].sort();
+}
+/**
+ * Paths a snapshot must NOT capture.
+ *
+ * Session and run logs are Layer 3 and travel by reference (spec s4), so
+ * capturing them here would duplicate them and, worse, let a stale copy overwrite
+ * the live append-only log on restore — the exact clobber the single-writer rule
+ * exists to prevent. Blobs are the session's own offloaded outputs, referenced
+ * the same way.
+ */
+export function isLayer3Path(path, stateDir) {
+    const p = path.replace(/^\.\//, '');
+    return p.startsWith(`${stateDir}/sessions/`)
+        || p.startsWith(`${stateDir}/runs/`)
+        || p === `${stateDir}/blobs`
+        || p.startsWith(`${stateDir}/blobs/`);
+}
+/** Drop Layer 3 paths from a tree before diffing it. */
+export function withoutLayer3(tree, stateDir) {
+    const out = {};
+    for (const [path, hash] of Object.entries(tree)) {
+        if (!isLayer3Path(path, stateDir))
+            out[path] = hash;
+    }
+    return out;
+}
+//# sourceMappingURL=tree.js.map

package/dist/snapshot/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../snapshot/tree.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins.d.ts

@@ -8,6 +8,7 @@ export declare const recallResultTool: AgentTool;
 export declare const askUserTool: AgentTool;
 export declare const spawnAgentTool: AgentTool;
 export declare const spawnAgentsTool: AgentTool;
+export declare const listToolsTool: AgentTool;
 export declare const compilePrompdTool: AgentTool;
 /** The kernel's runtime-agnostic built-in tools. Product/host tools (registry
  * search) are added by the registry — use `allTools()` for the complete set. */

package/dist/tools/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../tools/builtins.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,mBAAmB,CAAC;AAahE,eAAO,MAAM,eAAe,EAAE,SA0C7B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAoB5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAa9B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAWvB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAkBvB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAgB9B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,SAiDzB,CAAC;AAiBF,eAAO,MAAM,cAAc,EAAE,SA6B5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,SA6C7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,SAgC/B,CAAC;AAEF;gFACgF;AAChF,eAAO,MAAM,YAAY,EAAE,SAAS,EAenC,CAAC;AAEF;;;+DAG+D;AAC/D,wBAAgB,QAAQ,IAAI,SAAS,EAAE,CAEtC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../tools/builtins.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,mBAAmB,CAAC;AAwDhE,eAAO,MAAM,eAAe,EAAE,SA0F7B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAyB5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAa9B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAWvB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAkBvB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SA6B9B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,SAgEzB,CAAC;AAiBF,eAAO,MAAM,cAAc,EAAE,SA6B5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,SA6C7B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,SAoB3B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,SAgC/B,CAAC;AAEF;gFACgF;AAChF,eAAO,MAAM,YAAY,EAAE,SAAS,EAgBnC,CAAC;AAEF;;;+DAG+D;AAC/D,wBAAgB,QAAQ,IAAI,SAAS,EAAE,CAEtC"}

package/dist/tools/builtins.js

@@ -8,9 +8,55 @@ function str(args, key) {
     const v = args[key];
     return typeof v === 'string' ? v : v == null ? '' : String(v);
 }
+/* ---- propose_edit auto-correct ---- */
+/** Max consecutive proposals that failed to compile and were bounced back to the
+ * model for a fix, before a stubbornly-broken proposal falls through to human
+ * review instead of looping. The streak lives in ctx.runState (per-run), keyed
+ * here, so it can't leak or race across runs. */
+const MAX_AUTOFIX = 3;
+const AUTOFIX_KEY = 'proposeEditAutofixStreak';
+/** Read/advance the per-run auto-fix streak held in ctx.runState. */
+function autofixStreak(ctx) {
+    const rs = ctx.runState;
+    const cur = rs && typeof rs[AUTOFIX_KEY] === 'number' ? rs[AUTOFIX_KEY] : 0;
+    return {
+        value: cur,
+        bump() { if (rs)
+            rs[AUTOFIX_KEY] = cur + 1; },
+        reset() { if (rs)
+            rs[AUTOFIX_KEY] = 0; },
+    };
+}
+/** Only .prmd (always) and .md WITH frontmatter are worth compiling to validate —
+ * plain markdown has nothing to fail. Needs a known editor path for sibling
+ * resolution. */
+function shouldValidatePrmd(path, content) {
+    if (!path)
+        return false;
+    if (path.endsWith('.prmd'))
+        return true;
+    if (path.endsWith('.md'))
+        return content.trimStart().startsWith('---');
+    return false;
+}
+/** Compile the proposed content (resolving inherits:/{% include %} against the
+ * editor file's siblings) to validate it. Returns a formatted error list, or null
+ * when it compiles cleanly. Unfilled {{ params }} render empty (not an error), so a
+ * parameterized prompt still validates. */
+async function prmdCompileError(content, ctx) {
+    try {
+        const r = await compilePrompt(content, {}, { files: ctx.files, path: ctx.editorFile });
+        return r.errors?.length ? r.errors.map((e) => `- ${e.message}`).join('\n') : null;
+    }
+    catch (e) {
+        return `- ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
 export const proposeEditTool = {
     name: 'propose_edit',
-    description: 'Propose a replacement for the current editor file. The user reviews a diff and applies or rejects it — ' +
+    description: 'Propose a replacement for the CURRENTLY OPEN editor file. It takes no path and can only ever replace that '
+        + 'one file, so never use it to create a new file or to edit a different one — use create_file or write_file '
+        + 'for those. The user reviews a diff and applies or rejects it — ' +
         'this does NOT write the file directly. Provide the COMPLETE new file content (not a patch) plus a short ' +
         'explanation. Use the editor file shown in the system context as the basis. This call WAITS for the review ' +
         'and returns the outcome: applied, partially applied (with the rejected changes), or rejected — rely on ' +
@@ -20,11 +66,40 @@ export const proposeEditTool = {
         properties: {
             explanation: { type: 'string', description: 'One line describing the change.' },
             new_content: { type: 'string', description: 'The full proposed file content.' },
+            path: { type: 'string', description: 'The file being replaced. Must be the file currently open in the editor.' },
         },
-        required: ['explanation', 'new_content'],
+        required: ['explanation', 'new_content', 'path'],
     },
     async run(args, ctx) {
         const explanation = str(args, 'explanation') || 'Proposed an edit';
+        // Fail closed with no open file. This tool carries NO target path -- it replaces
+        // whatever the editor has open -- so without one there is nothing to diff
+        // against. Proposing anyway showed the user an empty diff, and (worse) content
+        // meant for a NEW file got diffed against an unrelated open document, where
+        // accepting would have overwritten it. Point the model at the tools that take
+        // an explicit path instead.
+        if (!ctx.editorFile) {
+            return 'Cannot propose an edit: no file is open in the editor, and propose_edit only replaces the open file. '
+                + 'To create a new file use create_file, and to overwrite an existing one use write_file — both take an explicit path.';
+        }
+        // The target is explicit and must be the open file. Before `path` existed this
+        // tool meant "the open file" implicitly, so a proposal authored for some OTHER
+        // file was silently diffed against whatever was open -- and accepting wrote the
+        // wrong content into it. Stating the target makes that mismatch impossible
+        // rather than merely unlikely.
+        const target = str(args, 'path');
+        if (!target) {
+            return `Cannot propose an edit: propose_edit needs a path, and it must be the open file (${ctx.editorFile}). `
+                + 'To create a new file use create_file, or to overwrite a different one use write_file.';
+        }
+        // Compare on a normalized form so a Windows path or a leading ./ is not a false
+        // mismatch — but nothing looser than that: matching on the basename alone would
+        // accept a/welcome.prmd for b/welcome.prmd, which is the very confusion this guards.
+        const norm = (p) => p.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+        if (norm(target) !== norm(ctx.editorFile)) {
+            return `Cannot propose an edit: the open file is ${ctx.editorFile}, but this proposal targets ${target}. `
+                + 'propose_edit can only replace the open file. Use create_file for a new file, or write_file to overwrite a different one.';
+        }
         // The diff + apply happen on the main thread (the panel renders the proposal
         // from this tool call). Block until the user decides so later turns can rely
         // on the outcome. Without a reviewer (sub-agents, DAG nodes, headless runs)
@@ -32,6 +107,21 @@ export const proposeEditTool = {
         if (!ctx.reviewEdit || !ctx.callId) {
             return `Proposed an edit: ${explanation}. Awaiting the user's review (apply/reject).`;
         }
+        // Auto-correct: validate the proposal BEFORE surfacing the diff. If it doesn't
+        // compile, bounce the errors back to the model to fix instead of showing the
+        // user a broken edit. Bounded — after MAX_AUTOFIX consecutive failures, fall
+        // through to human review so a stubbornly-broken proposal isn't hidden forever.
+        const newContent = str(args, 'new_content');
+        if (shouldValidatePrmd(ctx.editorFile, newContent)) {
+            const streak = autofixStreak(ctx);
+            const err = await prmdCompileError(newContent, ctx);
+            if (err && streak.value < MAX_AUTOFIX) {
+                streak.bump();
+                return ('This proposal does NOT compile, so it was not shown to the user. ' +
+                    `Fix these errors and call propose_edit again with corrected content:\n${err}`);
+            }
+            streak.reset(); // surfacing now (clean, or giving up after the budget)
+        }
         const outcome = ctx.signal.aborted ? null : await Promise.race([
             ctx.reviewEdit(ctx.callId),
             new Promise((resolve) => ctx.signal.addEventListener('abort', () => resolve(null), { once: true })),
@@ -52,21 +142,25 @@ export const proposeEditTool = {
 export const saveMemoryTool = {
     name: 'save_memory',
     mutates: true,
-    description: 'Persist a durable note to memory for later recall (facts, user preferences, decisions).',
+    description: 'Persist a durable note to memory for later recall (facts, user preferences, decisions). ' +
+        'Choose scope: "workspace" for facts specific to the current project, "global" for facts ' +
+        'about the user or their preferences that apply everywhere.',
     parameters: {
         type: 'object',
         properties: {
             text: { type: 'string', description: 'The note to remember.' },
+            scope: { type: 'string', enum: ['workspace', 'global'], description: 'Where to store it: workspace (this project) or global (everywhere).' },
             tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
         },
-        required: ['text'],
+        required: ['text', 'scope'],
     },
     // Permission is gated centrally by the loop's policy/permission layer (this
     // tool is `mutates`), so no confirm call here.
     async run(args, ctx) {
         const text = str(args, 'text');
         const tags = Array.isArray(args.tags) ? args.tags.map(String) : [];
-        const item = await ctx.memory.save(text, tags);
+        const scope = args.scope === 'global' ? 'global' : 'workspace';
+        const item = await ctx.memory.save(text, tags, scope);
         return `Saved memory ${item.id}.`;
     },
 };
@@ -117,6 +211,19 @@ export const kvSetTool = {
 export const recallResultTool = {
     name: 'recall_result',
     noOffload: true, // recalling a large result must never re-offload itself
+    /* DECLARED, like todo_write's and ask_user's. This one grants no new access at
+     * all: it reads back a tool result THIS SESSION ALREADY PRODUCED, which means
+     * the original call already passed the policy check that produced it. The
+     * store is session-scoped (`<root>/<sessionId>/blobs/<id>.json`) and the id
+     * shape is validated, so it cannot reach another session's data or escape the
+     * directory.
+     *
+     * The deciding argument is that offloading is a CONTEXT-MANAGEMENT detail,
+     * triggered by size. Gating recall means the same information costs an
+     * approval prompt depending on how large it happened to be - a performance
+     * heuristic leaking into governance, and an approval the user cannot act on
+     * meaningfully because they already approved the thing that produced it. */
+    permission: 'allow',
     description: 'Fetch the full content of a tool result that was offloaded to save context. ' +
         'You saw an "[offloaded tool result … recall_result({ id })]" reference — pass that id.',
     parameters: {
@@ -133,6 +240,21 @@ export const recallResultTool = {
 export const askUserTool = {
     name: 'ask_user',
     noOffload: true,
+    /* DECLARED, like todo_write's. Gating this behind an approval prompt is asking
+     * the user for permission to ask the user a question — two dialogs for one
+     * decision, the first of which carries no information.
+     *
+     * It changes nothing outside the run: no file, no network, no state. Its whole
+     * effect is to put a question in front of a person who is already there.
+     *
+     * Nothing depended on its previous `ask` tier. The case that looks like it
+     * might — an unattended run parking forever on a question nobody will answer —
+     * is handled by EXCLUSION rather than by permission: CREW_EXCLUDED_TOOLS drops
+     * ask_user from every crew agent (see @corenel/crew's capabilities.ts), and the
+     * daemon's executor honours the same set. On a surface where it IS offered,
+     * someone is by definition attending. And with no `ask` handler wired, `run`
+     * already returns "unavailable in this environment" rather than hanging. */
+    permission: 'allow',
     description: 'Ask the user one or more questions when you need a decision you cannot make from context — to choose ' +
         'between approaches, get a missing requirement, or confirm direction. Prefer this over guessing. Give each ' +
         'question a short `header` (a chip label), the `question` text, and 2–4 distinct `options` (each with a ' +
@@ -274,6 +396,28 @@ export const spawnAgentsTool = {
         return results.join('\n\n');
     },
 };
+export const listToolsTool = {
+    name: 'list_tools',
+    noOffload: true,
+    description: 'List the tools available to you this run — their names, one-line descriptions, and top-level parameters. ' +
+        'Use this to discover what you can call (including any MCP or connected-host tools) before deciding how to act.',
+    parameters: { type: 'object', properties: {} },
+    async run(_args, ctx) {
+        if (!ctx.listTools)
+            return 'Tool discovery is not available here.';
+        const tools = ctx.listTools();
+        if (!tools.length)
+            return 'No tools are available this run.';
+        const lines = tools.map((t) => {
+            const props = t.parameters && typeof t.parameters === 'object'
+                ? Object.keys(t.parameters.properties ?? {})
+                : [];
+            const params = props.length ? ` — params: ${props.join(', ')}` : '';
+            return `- \`${t.name}\`: ${t.description}${params}`;
+        });
+        return `Available tools this run (${tools.length}):\n${lines.join('\n')}`;
+    },
+};
 export const compilePrompdTool = {
     name: 'compile_prompd',
     noOffload: true, // the compiled output is what the user asked to see — keep inline
@@ -313,6 +457,7 @@ export const defaultTools = [
     askUserTool,
     spawnAgentTool,
     spawnAgentsTool,
+    listToolsTool,
     proposeEditTool,
     saveMemoryTool,
     recallMemoryTool,