@pugi/cli 0.1.0-beta.90 → 0.1.0-beta.91

package/dist/core/engine/tool-bridge.js

@@ -11,6 +11,7 @@ import { dispatchTodoWrite, todoWriteJsonSchema, } from '../../tools/todo-write.
 // JSON-schema fragment + a sentinel-returning dispatcher, matching the
 // `todo_write` / `ask_user_question` conventions.
 import { briefJsonSchema, dispatchBrief } from '../../tools/brief.js';
+import { cronCreateJsonSchema, cronDeleteJsonSchema, cronListJsonSchema, dispatchCronCreate, dispatchCronDelete, dispatchCronList, } from '../../tools/cron.js';
 import { dispatchVerifyPlanExecution, verifyPlanExecutionJsonSchema, } from '../../tools/verify-plan-execution.js';
 import { dispatchSleep, sleepJsonSchema } from '../../tools/sleep.js';
 import { dispatchSyntheticOutput, syntheticOutputJsonSchema, } from '../../tools/synthetic-output.js';
@@ -91,6 +92,17 @@ const READ_ONLY_TOOLS = new Set([
     // audit log (metadata, not source). Safe in plan mode — a planning
     // loop needs to verify its plan-capture steps before any writes.
     'verify_plan_execution',
+    // Backlog PUGI-7: cron_* tool family persists to `.pugi/cron/<name>.json`
+    // — metadata, not source. Plan mode keeps these available because
+    // planning a recurring workflow ("every Monday morning run the triple-
+    // review") is a configuration step the model should be able to take
+    // before any source mutation. The actual scheduler runner is gated by
+    // an explicit `pugi routines run` opt-in OUTSIDE the model surface, so
+    // even an aggressive plan-mode loop can only EDIT the routine registry
+    // here, never spawn a tick.
+    'cron_create',
+    'cron_delete',
+    'cron_list',
     // Tool gap pack : `sleep` is a no-op as far as the
     // workspace is concerned (wall-clock delay only). Plan mode keeps it
     // available so a planning loop can throttle its own polling.
@@ -157,6 +169,10 @@ const WIRED_TOOLS = new Set([
     'brief',
     // Backlog #5 P0 : verify_plan_execution anti-fake-dispatch gate.
     'verify_plan_execution',
+    // Backlog PUGI-7 : cron_* tool family (see READ_ONLY_TOOLS rationale).
+    'cron_create',
+    'cron_delete',
+    'cron_list',
     'sleep',
     // Tool gap pack: scratch-worktree primitives. Not in
     // READ_ONLY_TOOLS — they mutate workspace state (a new git worktree
@@ -325,6 +341,34 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
             'Optional: detail (<=2000 chars).',
         parameters: briefJsonSchema,
     });
+    // Backlog PUGI-7: cron_* tool family. Three tools that expose the
+    // local routine registry to the persona:
+    //   - cron_create — register a recurring routine. Writes one JSON
+    //     document per routine to `.pugi/cron/<name>.json` via atomic
+    //     tmp+rename. Replacing an existing name is intentional (the
+    //     name is the idempotency key).
+    //   - cron_delete — remove a routine by name. Idempotent.
+    //   - cron_list — list every registered routine, sorted by name.
+    // The scheduler runner (CronScheduler in core/cron/scheduler.ts) is
+    // OUT of this surface — these tools only EDIT the registry; ticking
+    // is gated by an explicit `pugi routines run` opt-in.
+    toolDefs.push({
+        name: 'cron_create',
+        description: 'Register a recurring routine. Required: name (slug), cronExpression (5-field), command (shell string). ' +
+            'Optional: args (string[]), description. Re-registering the same name REPLACES the prior routine. ' +
+            'Persisted atomically to .pugi/cron/<name>.json. Returns {ok, routine, replaced}.',
+        parameters: cronCreateJsonSchema,
+    }, {
+        name: 'cron_delete',
+        description: 'Remove a routine by name. Idempotent — deleting an unknown name returns ok:true with removed:false. ' +
+            'Returns {ok, removed, name}.',
+        parameters: cronDeleteJsonSchema,
+    }, {
+        name: 'cron_list',
+        description: 'List every registered routine, sorted by name. Zero routines returns {routines:[]} — never an error. ' +
+            'No arguments.',
+        parameters: cronListJsonSchema,
+    });
     // Backlog #5 P0 : verify_plan_execution — anti-fake-dispatch gate.
     // Reads the session audit log (metadata only, no source mutation). Plan-mode
     // safe: a plan-loop frequently needs к verify its plan-capture steps before
@@ -1137,6 +1181,23 @@ export function buildExecutor(input) {
                 // earlier turns in the same engine loop invocation).
                 return dispatchVerifyPlanExecution(ctx.session, args);
             }
+            if (name === 'cron_create') {
+                // Backlog PUGI-7: ScheduleCronTool — register a routine. The
+                // dispatcher returns a JSON string envelope (success) or a
+                // CRON_INVALID_ARGS / CRON_PERSIST_FAILED sentinel (recoverable
+                // failures). Sentinels surface as plain tool results so the
+                // model can self-correct.
+                return dispatchCronCreate({ workspaceRoot }, args);
+            }
+            if (name === 'cron_delete') {
+                // Backlog PUGI-7: idempotent routine removal.
+                return dispatchCronDelete({ workspaceRoot }, args);
+            }
+            if (name === 'cron_list') {
+                // Backlog PUGI-7: routine registry snapshot. Read-only; safe
+                // for parallel dispatch.
+                return dispatchCronList({ workspaceRoot }, args);
+            }
             if (name === 'sleep') {
                 return dispatchSleep({}, args);
             }

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.90');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.91');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/cron.js

@@ -0,0 +1,433 @@
+/**
+ * cron_* tool family — ScheduleCronTool / CronList / CronDelete (PUGI-7).
+ *
+ * Three tools that expose the local cron-routine surface to the persona:
+ *
+ *  - `cron_create` — register a recurring routine. Writes one JSON
+ *    document per routine to `.pugi/cron/<name>.json` via the atomic
+ *    tmp+rename pattern.
+ *  - `cron_delete` — remove a routine by name. Idempotent: deleting an
+ *    unknown name returns `{ ok: true, removed: false }` instead of
+ *    throwing, so the model never wedges on a stale routine list.
+ *  - `cron_list` — return every registered routine, sorted by name.
+ *    An empty registry returns `{ routines: [] }`, NOT an error.
+ *
+ * Why one JSON document per routine instead of a single `routines.json`
+ * board: routines are independent — there is no cross-routine invariant
+ * (unlike the `todo_write` single-in-progress rule). Per-file storage
+ * means a corrupt or partially-written routine cannot poison the
+ * others, and the atomic tmp+rename pattern is a one-file-at-a-time
+ * primitive that maps cleanly to per-file persistence.
+ *
+ * Why hand-rolled JSON-Schema instead of zod-to-json-schema: matches
+ * the project-wide convention (see brief.ts §note) — we have not
+ * greenlit the runtime dependency, and the schemas here are small
+ * enough to author by hand without drift risk.
+ *
+ * Cron expression validation: delegates to node-cron's `validate()` via
+ * `isValidCronExpression()` in core/cron/scheduler.ts. node-cron handles
+ * 5-field standard expressions plus the common shortcuts. We do NOT
+ * roll our own regex because cron has too many edge cases (step values,
+ * ranges with step, named months/days) and a partial regex silently
+ * accepts garbage the scheduler later rejects.
+ *
+ * On duplicate name during cron_create: the second call REPLACES the
+ * first, mirroring `CronScheduler.schedule()` which also replaces. The
+ * dispatcher returns `{ ok: true, replaced: true }` so the model and
+ * the operator can see the swap happened. Rationale: a routine name is
+ * an idempotency key; if the model re-registers the same logical
+ * routine with a tweaked expression we want the new shape to win
+ * rather than failing the call and leaving stale state.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isValidCronExpression } from '../core/cron/scheduler.js';
+/** Maximum routine name length. Kept small so it renders cleanly in
+ * the operator-facing `pugi routines list` table. */
+export const CRON_NAME_MAX = 64;
+/** Maximum command length. The routine executes a shell command, so
+ * the cap mirrors the operator-facing brief detail cap — long enough
+ * for a realistic invocation, short enough to log without truncation. */
+export const CRON_COMMAND_MAX = 2_000;
+/** Maximum description length. Free-form prose, capped to fit one
+ * paragraph in the routines table. */
+export const CRON_DESCRIPTION_MAX = 500;
+/** Maximum number of positional args. A large arg list is a smell —
+ * the model should wrap into a single script invocation instead. */
+export const CRON_ARGS_MAX = 32;
+/** Maximum per-arg length. Same rationale as CRON_COMMAND_MAX. */
+export const CRON_ARG_LEN_MAX = 500;
+/** Sentinel returned when input fails schema validation. Mirrors
+ * `BRIEF_INVALID_ARGS` / `VERIFY_PLAN_INVALID_ARGS` so the dispatcher
+ * pattern-matches the prefix for retry-budget bookkeeping. */
+export const CRON_INVALID_ARGS = 'CRON_INVALID_ARGS';
+/** Sentinel returned when a registry write fails for an
+ * environment-level reason (filesystem full, permission denied). */
+export const CRON_PERSIST_FAILED = 'CRON_PERSIST_FAILED';
+/** Allowed routine name pattern. Slug-shaped so the name maps 1:1 to
+ * a safe filesystem basename — no separators, no shell metacharacters,
+ * no leading dot. */
+const CRON_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+/* -------------------------------------------------------------------------- */
+/* parse helpers                                                              */
+/* -------------------------------------------------------------------------- */
+export function parseCronCreateArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${CRON_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const name = obj['name'];
+    if (typeof name !== 'string') {
+        issues.push('name: must be a string');
+    }
+    else if (name.length === 0) {
+        issues.push('name: must be non-empty');
+    }
+    else if (name.length > CRON_NAME_MAX) {
+        issues.push(`name: must be <= ${CRON_NAME_MAX} chars`);
+    }
+    else if (!CRON_NAME_RE.test(name)) {
+        issues.push('name: must match /^[a-z][a-z0-9_-]{0,63}$/ (lowercase, no separators, no leading digit)');
+    }
+    const cronExpression = obj['cronExpression'];
+    if (typeof cronExpression !== 'string') {
+        issues.push('cronExpression: must be a string');
+    }
+    else if (cronExpression.trim().length === 0) {
+        issues.push('cronExpression: must be non-empty');
+    }
+    else if (!isValidCronExpression(cronExpression)) {
+        issues.push('cronExpression: must be a valid 5-field cron expression (see https://crontab.guru)');
+    }
+    const command = obj['command'];
+    if (typeof command !== 'string') {
+        issues.push('command: must be a string');
+    }
+    else if (command.trim().length === 0) {
+        issues.push('command: must be non-empty');
+    }
+    else if (command.length > CRON_COMMAND_MAX) {
+        issues.push(`command: must be <= ${CRON_COMMAND_MAX} chars`);
+    }
+    let args;
+    if (obj['args'] !== undefined && obj['args'] !== null) {
+        if (!Array.isArray(obj['args'])) {
+            issues.push('args: must be an array of strings when present');
+        }
+        else if (obj['args'].length > CRON_ARGS_MAX) {
+            issues.push(`args: must have <= ${CRON_ARGS_MAX} entries`);
+        }
+        else {
+            args = [];
+            for (let i = 0; i < obj['args'].length; i++) {
+                const a = obj['args'][i];
+                if (typeof a !== 'string') {
+                    issues.push(`args[${i}]: must be a string`);
+                }
+                else if (a.length > CRON_ARG_LEN_MAX) {
+                    issues.push(`args[${i}]: must be <= ${CRON_ARG_LEN_MAX} chars`);
+                }
+                else {
+                    args.push(a);
+                }
+            }
+        }
+    }
+    let description;
+    if (obj['description'] !== undefined && obj['description'] !== null) {
+        if (typeof obj['description'] !== 'string') {
+            issues.push('description: must be a string when present');
+        }
+        else if (obj['description'].length > CRON_DESCRIPTION_MAX) {
+            issues.push(`description: must be <= ${CRON_DESCRIPTION_MAX} chars`);
+        }
+        else {
+            description = obj['description'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${CRON_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const result = {
+        name: name,
+        cronExpression: cronExpression,
+        command: command,
+        ...(args !== undefined ? { args } : {}),
+        ...(description !== undefined ? { description } : {}),
+    };
+    return result;
+}
+export function parseCronDeleteArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${CRON_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const name = obj['name'];
+    if (typeof name !== 'string') {
+        return `${CRON_INVALID_ARGS}: name: must be a string`;
+    }
+    if (name.length === 0) {
+        return `${CRON_INVALID_ARGS}: name: must be non-empty`;
+    }
+    if (name.length > CRON_NAME_MAX) {
+        return `${CRON_INVALID_ARGS}: name: must be <= ${CRON_NAME_MAX} chars`;
+    }
+    if (!CRON_NAME_RE.test(name)) {
+        return `${CRON_INVALID_ARGS}: name: must match /^[a-z][a-z0-9_-]{0,63}$/`;
+    }
+    return { name };
+}
+/* -------------------------------------------------------------------------- */
+/* path resolution                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Compute the on-disk path for a routine's JSON document. Public so
+ * future surfaces (`pugi routines show <name>`) can share the layout
+ * rules without duplicating string composition.
+ */
+export function cronRoutinePath(ctx, name) {
+    // Defense in depth: the name is already validated by the parse layer,
+    // but a direct programmatic caller (tests, future internal hooks)
+    // might skip parsing. Re-check the slug shape here so we never compose
+    // a path that escapes the cron directory.
+    if (!CRON_NAME_RE.test(name)) {
+        throw new Error(`cron: invalid routine name shape: "${name}"`);
+    }
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'cron', `${name}.json`);
+}
+function cronDir(ctx) {
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'cron');
+}
+/* -------------------------------------------------------------------------- */
+/* persistence                                                                */
+/* -------------------------------------------------------------------------- */
+let cronSequence = 0;
+/**
+ * Atomic write: serialise -> sibling tmp file -> rename. POSIX-portable
+ * and atomic on the same filesystem so a concurrent `cron_list` reader
+ * never observes a half-written routine document.
+ */
+function persistRoutine(ctx, routine) {
+    const dir = cronDir(ctx);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const finalPath = cronRoutinePath(ctx, routine.name);
+    const body = `${JSON.stringify(routine, null, 2)}\n`;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${cronSequence++}`;
+    writeFileSync(tmpPath, body, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmpPath, finalPath);
+}
+function loadRoutine(ctx, name) {
+    const path = cronRoutinePath(ctx, name);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isValidLoadedRoutine(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        // A corrupt or partially-written file is treated as "no routine
+        // here" — the next cron_create call replaces it cleanly. We do not
+        // surface the parse error because the model cannot act on it.
+        return null;
+    }
+}
+function isValidLoadedRoutine(value) {
+    return (typeof value.name === 'string' &&
+        typeof value.cronExpression === 'string' &&
+        typeof value.command === 'string' &&
+        Array.isArray(value.args) &&
+        typeof value.createdAt === 'string' &&
+        typeof value.updatedAt === 'string');
+}
+/* -------------------------------------------------------------------------- */
+/* dispatchers                                                                */
+/* -------------------------------------------------------------------------- */
+function nowIso(ctx) {
+    return (ctx.now ? ctx.now() : new Date()).toISOString();
+}
+/**
+ * Dispatch entry for `cron_create`. Returns a JSON-string envelope so
+ * the engine adapter can surface structured data to the persona model
+ * without bespoke parsing. Mirrors the brief/todo_write dispatcher
+ * shape (string return for sentinel routing, JSON-string for success).
+ */
+export function dispatchCronCreate(ctx, raw) {
+    const parsed = parseCronCreateArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const at = nowIso(ctx);
+    const existing = loadRoutine(ctx, parsed.name);
+    const routine = {
+        name: parsed.name,
+        cronExpression: parsed.cronExpression,
+        command: parsed.command,
+        args: parsed.args ?? [],
+        ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+        createdAt: existing ? existing.createdAt : at,
+        updatedAt: at,
+    };
+    try {
+        persistRoutine(ctx, routine);
+    }
+    catch (error) {
+        return `${CRON_PERSIST_FAILED}: ${error.message}`;
+    }
+    const result = {
+        ok: true,
+        routine,
+        replaced: existing !== null,
+    };
+    return JSON.stringify(result);
+}
+/**
+ * Dispatch entry for `cron_delete`. Idempotent: a delete of an unknown
+ * routine returns `{ ok: true, removed: false }` rather than a 404-
+ * shaped sentinel. Rationale: the persona's mental model of "the
+ * routine is gone" is satisfied either way, and treating delete as
+ * idempotent avoids the model spinning on a stale routine that was
+ * already cleaned up by a parallel operator action.
+ */
+export function dispatchCronDelete(ctx, raw) {
+    const parsed = parseCronDeleteArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const path = cronRoutinePath(ctx, parsed.name);
+    let removed = false;
+    if (existsSync(path)) {
+        try {
+            unlinkSync(path);
+            removed = true;
+        }
+        catch (error) {
+            return `${CRON_PERSIST_FAILED}: ${error.message}`;
+        }
+    }
+    const result = {
+        ok: true,
+        removed,
+        name: parsed.name,
+    };
+    return JSON.stringify(result);
+}
+/**
+ * Dispatch entry for `cron_list`. Returns every registered routine,
+ * sorted by name. Zero routines returns an empty array (`{ routines:
+ * [] }`), never an error — an empty registry is the steady state on a
+ * fresh workspace and the model should not have to special-case it.
+ *
+ * `cron_list` accepts no arguments. We still parse the input so that a
+ * model that sends a stray object (because its tool grammar emits
+ * `{}` by default) does not crash; only an explicit non-object value
+ * is rejected with `CRON_INVALID_ARGS`.
+ */
+export function dispatchCronList(ctx, raw) {
+    if (raw !== undefined && raw !== null) {
+        if (typeof raw !== 'object' || Array.isArray(raw)) {
+            return `${CRON_INVALID_ARGS}: arguments must be a JSON object or omitted`;
+        }
+    }
+    const dir = cronDir(ctx);
+    const routines = [];
+    if (existsSync(dir)) {
+        const entries = readdirSync(dir).filter((e) => e.endsWith('.json'));
+        for (const entry of entries) {
+            const name = entry.slice(0, -'.json'.length);
+            // The persistence layer only writes files with slug-safe names,
+            // but a manual edit (operator hand-rolled a file) might violate
+            // the shape. Skip such entries instead of crashing the list call.
+            if (!CRON_NAME_RE.test(name))
+                continue;
+            const routine = loadRoutine(ctx, name);
+            if (routine)
+                routines.push(routine);
+        }
+        routines.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const result = { routines };
+    return JSON.stringify(result);
+}
+/* -------------------------------------------------------------------------- */
+/* JSON-Schema fragments (engine-side tool definitions)                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * JSON-Schema for cron_create. Mirrors `parseCronCreateArgs` checks
+ * 1:1. Hand-rolled per the project convention (see brief.ts §note on
+ * zod-to-json-schema).
+ */
+export const cronCreateJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name', 'cronExpression', 'command'],
+    properties: {
+        name: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_NAME_MAX,
+            pattern: '^[a-z][a-z0-9_-]{0,63}$',
+            description: 'Routine name (slug-shaped, lowercase). Doubles as the on-disk basename and the idempotency key — re-registering with the same name REPLACES the prior routine.',
+        },
+        cronExpression: {
+            type: 'string',
+            minLength: 1,
+            description: 'Standard 5-field cron expression (minute hour day-of-month month day-of-week). Example: "0 9 * * 1-5" runs at 09:00 on weekdays. Validated by node-cron.',
+        },
+        command: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_COMMAND_MAX,
+            description: 'Shell command to execute on each tick. Example: "pugi review --triple --remote". The command is stored verbatim; the runner spawns it without word-splitting.',
+        },
+        args: {
+            type: 'array',
+            maxItems: CRON_ARGS_MAX,
+            items: {
+                type: 'string',
+                maxLength: CRON_ARG_LEN_MAX,
+            },
+            description: 'Optional positional arguments passed to <command> as a separate argv array. Prefer this over embedding shell metacharacters in <command>.',
+        },
+        description: {
+            type: 'string',
+            maxLength: CRON_DESCRIPTION_MAX,
+            description: 'Optional one-paragraph description. Surfaces in `pugi routines list` so an operator can audit unfamiliar routines.',
+        },
+    },
+};
+/**
+ * JSON-Schema for cron_delete. Single-field shape — name only.
+ */
+export const cronDeleteJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name'],
+    properties: {
+        name: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_NAME_MAX,
+            pattern: '^[a-z][a-z0-9_-]{0,63}$',
+            description: 'Routine name to delete. Idempotent: an unknown name returns ok:true with removed:false instead of erroring.',
+        },
+    },
+};
+/**
+ * JSON-Schema for cron_list. Zero-field shape — every list returns the
+ * full registry. We expose an empty `additionalProperties: false`
+ * object so the schema-aware engine knows the tool takes no input.
+ */
+export const cronListJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {},
+};
+//# sourceMappingURL=cron.js.map

package/dist/tools/registry.js

@@ -21,6 +21,19 @@ const registry = [
     // Backlog #5 P0 : verify_plan_execution anti-fake-dispatch gate.
     // Reads session audit events only; safe для parallel dispatches.
     { name: 'verify_plan_execution', permission: 'none', risk: 'low', concurrencySafe: true, m1: false },
+    // Backlog PUGI-7 : cron_* tool family. Persists routine registry to
+    // `.pugi/cron/<name>.json` (one file per routine, atomic tmp+rename).
+    // Permission = none because the writes land in metadata, not source —
+    // mirrors the brief / todo_write posture. concurrencySafe = false for
+    // create + delete because per-file persistence is atomic individually
+    // but two parallel creates of the SAME name race on the rename and
+    // the loser's body is dropped silently; cron_list is read-only and
+    // safe for concurrent dispatch. Risk = low across the board: routines
+    // are configuration objects, the actual scheduler runner lives behind
+    // an explicit `pugi routines run` opt-in and is OUT of this surface.
+    { name: 'cron_create', permission: 'none', risk: 'low', concurrencySafe: false, m1: false },
+    { name: 'cron_delete', permission: 'none', risk: 'low', concurrencySafe: false, m1: false },
+    { name: 'cron_list', permission: 'none', risk: 'low', concurrencySafe: true, m1: false },
     { name: 'edit', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
     // Tool gap pack : scratch worktree open. Spawns
     // `git worktree add` under `.pugi/worktrees/<taskId>/`. Permission =

package/dist/tui/multi-file-diff-approval.js

@@ -0,0 +1,375 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * MultiFileDiffApproval — side-by-side multi-file diff approval modal
+ * (PUGI-68).
+ *
+ * When the engine proposes a batch of edits that touches more than one
+ * file, the operator needs to review every diff in a single coherent
+ * view, then accept-all / reject-all / per-file approve before the
+ * dispatcher applies anything. The single-file approval surfaces in
+ * the AskModal / PlanReviewModal family are insufficient — a per-file
+ * back-to-back prompt loses the cross-file context the operator needs
+ * to spot a regression that spans modules.
+ *
+ * Layout (matches the AskUserQuestionChips PUGI-130 side-by-side
+ * precedent, see `ask-user-question-chips.tsx`):
+ *
+ *   ┌─ Multi-file diff review ───────────────────────────────────────┐
+ *   │ ┌─ Files ─────────────┐ ┌─ Diff: src/foo/bar.ts ─────────────┐ │
+ *   │ │ ▸ • src/foo/bar.ts  │ │ --- src/foo/bar.ts                 │ │
+ *   │ │   ✓ src/baz.ts      │ │ +++ src/foo/bar.ts                 │ │
+ *   │ │   ✗ src/qux.ts      │ │ @@ -1,4 +1,4 @@                    │ │
+ *   │ │     • src/x/y.ts    │ │ -const x = 1;                      │ │
+ *   │ │                     │ │ +const x = 2;                      │ │
+ *   │ └─────────────────────┘ └────────────────────────────────────┘ │
+ *   │ 1/4 approved · 1/4 rejected · 2 remaining · Enter when done    │
+ *   └────────────────────────────────────────────────────────────────┘
+ *
+ * Key bindings:
+ *  - ↑ / ↓ ............ navigate the file list
+ *  - a ................ approve the highlighted file
+ *  - r ................ reject the highlighted file
+ *  - A (shift+a) ...... approve every file in the batch
+ *  - R (shift+r) ...... reject every file in the batch
+ *  - PgUp / PgDn ...... scroll the diff pane
+ *  - Enter ............ finalise — emit per-file verdicts
+ *  - Esc .............. cancel the whole batch (every file → rejected)
+ *
+ * Contract notes:
+ *  - The component is PURE (Ink-style). It mounts useState for cursor,
+ *    per-file verdict map, and diff-pane scroll offset. Emits exactly
+ *    one `onResolve` callback when the operator presses Enter (or Esc
+ *    for a cancel).
+ *  - Per-file diff bodies are rendered verbatim from the provided
+ *    unified-diff text — the component does NOT compute diffs from raw
+ *    file contents. Callers (typically the dispatcher result transcript)
+ *    own the diff text generation.
+ *  - Long file paths are truncated middle-style so prefix + suffix stay
+ *    visible (the parts the operator scans for module scope + filename).
+ *  - Long diff bodies scroll via a single-axis offset; horizontal
+ *    overflow is left to Ink's text wrapping per line. No mouse support.
+ *
+ * Brand voice gate: ASCII glyphs only (✓ / ✗ kept for status — already
+ * shipped в other TUI components like agent-progress-card). No banned
+ * brand words, no em-dashes, no attribution to external AIs.
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+/* ------------------------------------------------------------------ */
+/* Defensive caps                                                      */
+/* ------------------------------------------------------------------ */
+/** Maximum chars rendered per file path in the left pane. */
+export const MULTI_FILE_DIFF_PATH_CAP = 48;
+/** Visible rows in the diff pane viewport. */
+export const MULTI_FILE_DIFF_PANE_HEIGHT = 18;
+/** Width hint for the left file-list column (used for path truncation). */
+export const MULTI_FILE_DIFF_LEFT_WIDTH = 32;
+/** Hard cap on diff body length (chars) — defends against runaway model output. */
+export const MULTI_FILE_DIFF_BODY_CHAR_CAP = 200_000;
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Middle-truncate a long file path so both prefix (module scope) and
+ * suffix (filename) stay visible. Mirrors the macOS `truncate=middle`
+ * convention. Appends `…` in the middle when truncation happens.
+ *
+ * Examples (cap = 24):
+ *   "src/foo/bar/baz/qux.ts"      → "src/foo/bar/baz/qux.ts"  (fits)
+ *   "src/a-long-module/b/c/d.ts"  → "src/a-long-mo…/b/c/d.ts" (cut middle)
+ *
+ * Exported so the spec can assert the contract directly.
+ */
+export function truncateMiddle(raw, cap) {
+    if (cap <= 1)
+        return '…';
+    if (raw.length <= cap)
+        return raw;
+    // Reserve one slot for the ellipsis; balance prefix/suffix around it.
+    // The suffix gets one extra char on odd budgets so the filename stays
+    // longer (operators scan filenames more than the path prefix).
+    const remaining = cap - 1;
+    const prefixLen = Math.floor(remaining / 2);
+    const suffixLen = remaining - prefixLen;
+    return `${raw.slice(0, prefixLen)}…${raw.slice(raw.length - suffixLen)}`;
+}
+/**
+ * Defensive char cap on the diff body. Schema-level caps live upstream;
+ * this is belt + braces against a malformed dispatcher transcript that
+ * could otherwise exhaust the terminal scrollback.
+ */
+export function clampDiffBody(raw) {
+    if (raw.length <= MULTI_FILE_DIFF_BODY_CHAR_CAP)
+        return raw;
+    return `${raw.slice(0, MULTI_FILE_DIFF_BODY_CHAR_CAP - 1)}…`;
+}
+export function classifyDiffLine(line) {
+    if (line.startsWith('+++') || line.startsWith('---'))
+        return 'file-header';
+    if (line.startsWith('@@'))
+        return 'hunk-header';
+    if (line.startsWith('+'))
+        return 'addition';
+    if (line.startsWith('-'))
+        return 'deletion';
+    return 'context';
+}
+/** Inline helper — return per-line render props for a diff line. */
+function renderProps(kind) {
+    switch (kind) {
+        case 'file-header':
+            return { bold: true };
+        case 'hunk-header':
+            return { color: 'blue', bold: true };
+        case 'addition':
+            return { color: 'green' };
+        case 'deletion':
+            return { color: 'red' };
+        case 'context':
+            return { dimColor: true };
+    }
+}
+/**
+ * Public verdict-encoder mirror of the AskModal / PlanReviewModal
+ * encoders. Surfaces a single human-readable summary string the caller
+ * can inject as the next operator turn or log to a session journal.
+ *
+ *  - `cancelled`        → "[MULTI-DIFF-VERDICT:cancelled]"
+ *  - all approved       → "[MULTI-DIFF-VERDICT:all-approved] file1; file2"
+ *  - all rejected       → "[MULTI-DIFF-VERDICT:all-rejected] file1; file2"
+ *  - mixed              → "[MULTI-DIFF-VERDICT:mixed] +file1; -file2; ?file3"
+ *
+ * Each per-file token in mixed mode is prefixed `+` (approved), `-`
+ * (rejected), or `?` (still pending — operator hit Enter без deciding).
+ */
+export function encodeMultiFileDiffVerdict(result) {
+    if (result.cancelled)
+        return '[MULTI-DIFF-VERDICT:cancelled]';
+    const total = result.verdicts.length;
+    if (total === 0)
+        return '[MULTI-DIFF-VERDICT:empty]';
+    const allApproved = result.verdicts.every((v) => v.verdict === 'approved');
+    const allRejected = result.verdicts.every((v) => v.verdict === 'rejected');
+    if (allApproved) {
+        return `[MULTI-DIFF-VERDICT:all-approved] ${result.verdicts
+            .map((v) => v.path)
+            .join('; ')}`;
+    }
+    if (allRejected) {
+        return `[MULTI-DIFF-VERDICT:all-rejected] ${result.verdicts
+            .map((v) => v.path)
+            .join('; ')}`;
+    }
+    const tokens = result.verdicts.map((v) => {
+        const prefix = v.verdict === 'approved' ? '+' : v.verdict === 'rejected' ? '-' : '?';
+        return `${prefix}${v.path}`;
+    });
+    return `[MULTI-DIFF-VERDICT:mixed] ${tokens.join('; ')}`;
+}
+/* ------------------------------------------------------------------ */
+/* Component                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Build the result object for a given verdict map + entries vector.
+ * Hoisted because both the commit (Enter) and cancel (Esc) paths need
+ * to project the same shape — cancel just overrides every verdict to
+ * `rejected` and stamps `cancelled: true`.
+ */
+function buildResult(entries, verdicts, cancelled) {
+    const projected = entries.map((entry, idx) => ({
+        path: entry.path,
+        verdict: verdicts[idx] ?? 'pending',
+    }));
+    return {
+        verdicts: projected,
+        approvedPaths: projected
+            .filter((v) => v.verdict === 'approved')
+            .map((v) => v.path),
+        rejectedPaths: projected
+            .filter((v) => v.verdict === 'rejected')
+            .map((v) => v.path),
+        cancelled,
+    };
+}
+export function MultiFileDiffApproval(props) {
+    // FIX (PR #876 triple-review): the previous `useMemo(() => props.entries,
+    // [props.entries])` was a no-op — it returned the same reference it
+    // depended on, so the memo never produced a stable identity gain. We
+    // reference `props.entries` directly now; downstream useEffect /
+    // useMemo hooks key on the real prop, not a redundant wrapper.
+    const entries = props.entries;
+    const paneHeight = props.paneHeight ?? MULTI_FILE_DIFF_PANE_HEIGHT;
+    const [cursor, setCursor] = useState(0);
+    const [verdicts, setVerdicts] = useState(() => entries.map(() => 'pending'));
+    const [scrollOffset, setScrollOffset] = useState(0);
+    // FIX (PR #876 triple-review, P1): the lazy useState initialiser
+    // captures `entries.length` ONCE at mount. If the caller swaps in
+    // a different entries array (length mismatch), the verdicts vector
+    // would drift — `setVerdictAt` could index out of range or
+    // `buildResult` could project a `pending` for a real entry whose
+    // verdict the operator already set. Re-sync on length change while
+    // preserving existing per-index verdicts (forgiving variant A).
+    useEffect(() => {
+        setVerdicts((prev) => {
+            if (prev.length === entries.length)
+                return prev;
+            return entries.map((_, i) => prev[i] ?? 'pending');
+        });
+        // Also clamp the cursor so it never points past the new end.
+        setCursor((c) => {
+            if (entries.length === 0)
+                return 0;
+            return Math.min(c, entries.length - 1);
+        });
+    }, [entries.length, entries]);
+    // FIX (PR #876 triple-review, P1): `commit()` is called from inside
+    // the useInput closure, which captures the `verdicts` value at the
+    // render time the closure was created. With rapid keypresses (e.g.
+    // `a` then Enter on the same React tick), React has scheduled the
+    // setVerdicts update but the closure still sees the previous array.
+    // The emitted MultiFileDiffResult would drop the latest verdict.
+    // Fix: track verdicts via a ref synced in a useEffect — the commit
+    // path reads `verdictsRef.current` so it always sees the latest map.
+    const verdictsRef = useRef(verdicts);
+    useEffect(() => {
+        verdictsRef.current = verdicts;
+    }, [verdicts]);
+    // Pre-split the active diff body into lines for the right pane. The
+    // body is clamped defensively before splitting so a runaway model
+    // payload cannot exhaust the terminal scrollback. useMemo here keeps
+    // the line array stable across navigation re-renders on the SAME
+    // file — only the cursor changes when the operator presses ↑/↓ on
+    // the same diff body.
+    const activeEntry = entries[cursor];
+    const activeLines = useMemo(() => {
+        const body = clampDiffBody(activeEntry?.diff ?? '');
+        if (body.length === 0)
+            return [];
+        return body.split('\n');
+    }, [activeEntry?.diff]);
+    function commit(cancelled = false) {
+        // Read the freshest verdict map via ref — the closure-captured
+        // `verdicts` state could be one render behind on rapid keypresses.
+        const latest = verdictsRef.current;
+        const finalVerdicts = cancelled
+            ? entries.map(() => 'rejected')
+            : latest;
+        props.onResolve(buildResult(entries, finalVerdicts, cancelled));
+    }
+    function setVerdictAt(idx, verdict) {
+        setVerdicts((prev) => {
+            const next = prev.slice();
+            next[idx] = verdict;
+            return next;
+        });
+    }
+    function setAllVerdicts(verdict) {
+        setVerdicts(() => entries.map(() => verdict));
+    }
+    useInput((input, key) => {
+        // Esc cancels the whole batch (every file → rejected). Mirrors the
+        // AskModal cancel contract so operator muscle memory transfers.
+        if (key.escape) {
+            commit(true);
+            return;
+        }
+        // Enter commits the current verdict map. Pending files stay
+        // pending — the caller decides whether `pending` is treated as
+        // approve or reject (dispatcher policy lives upstream).
+        if (key.return) {
+            commit(false);
+            return;
+        }
+        // ↑ / ↓ navigate file list. Reset scroll on file change so the
+        // operator sees the diff header again, not a stale offset from
+        // the previous file.
+        if (key.upArrow) {
+            if (entries.length === 0)
+                return;
+            setCursor((c) => (c - 1 + entries.length) % entries.length);
+            setScrollOffset(0);
+            return;
+        }
+        if (key.downArrow) {
+            if (entries.length === 0)
+                return;
+            setCursor((c) => (c + 1) % entries.length);
+            setScrollOffset(0);
+            return;
+        }
+        // PgUp / PgDn scroll the diff pane by a near-full viewport. We
+        // keep one row of overlap so the operator's eye anchors across
+        // pages. Clamped to [0, max] so over-scroll stops at the bottom
+        // line instead of producing an empty pane.
+        if (key.pageUp) {
+            setScrollOffset((o) => Math.max(0, o - Math.max(1, paneHeight - 1)));
+            return;
+        }
+        if (key.pageDown) {
+            setScrollOffset((o) => {
+                const maxOffset = Math.max(0, activeLines.length - paneHeight);
+                return Math.min(maxOffset, o + Math.max(1, paneHeight - 1));
+            });
+            return;
+        }
+        // Capital A / R = bulk verdict. Lowercase a / r = per-file. The
+        // order matters: Ink delivers SHIFTed keys as the upper-case
+        // glyph in `input`, so we can match с a direct equality.
+        if (input === 'A') {
+            setAllVerdicts('approved');
+            return;
+        }
+        if (input === 'R') {
+            setAllVerdicts('rejected');
+            return;
+        }
+        if (input === 'a') {
+            setVerdictAt(cursor, 'approved');
+            return;
+        }
+        if (input === 'r') {
+            setVerdictAt(cursor, 'rejected');
+            return;
+        }
+    }, { isActive: props.inert !== true });
+    const approvedCount = verdicts.filter((v) => v === 'approved').length;
+    const rejectedCount = verdicts.filter((v) => v === 'rejected').length;
+    const pendingCount = verdicts.filter((v) => v === 'pending').length;
+    const total = entries.length;
+    // Diff pane viewport: a window of `paneHeight` lines starting at
+    // scrollOffset. Empty entries render с a placeholder so the operator
+    // sees the file is intentionally empty (vs the modal being broken).
+    const visibleLines = activeLines.slice(scrollOffset, scrollOffset + paneHeight);
+    const diffPaneTitle = activeEntry
+        ? `Diff: ${truncateMiddle(activeEntry.path, MULTI_FILE_DIFF_PATH_CAP)}`
+        : 'Diff';
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: '? ' }), _jsx(Text, { bold: true, children: `Multi-file diff review (${total} ${total === 1 ? 'file' : 'files'})` })] }), _jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, marginRight: 1, minWidth: MULTI_FILE_DIFF_LEFT_WIDTH, children: [_jsx(Box, { children: _jsx(Text, { bold: true, dimColor: true, children: 'Files' }) }), entries.map((entry, idx) => {
+                                const isHighlighted = idx === cursor;
+                                const verdict = verdicts[idx] ?? 'pending';
+                                // Badge: ✓ approved (green), ✗ rejected (red), • pending (dim).
+                                // The badge sits BEFORE the cursor arrow so the operator can
+                                // skim status without scanning the cursor column.
+                                let badgeGlyph = '•';
+                                let badgeColor;
+                                let badgeDim = true;
+                                if (verdict === 'approved') {
+                                    badgeGlyph = '✓';
+                                    badgeColor = 'green';
+                                    badgeDim = false;
+                                }
+                                else if (verdict === 'rejected') {
+                                    badgeGlyph = '✗';
+                                    badgeColor = 'red';
+                                    badgeDim = false;
+                                }
+                                // Path budget = left width minus borders, cursor arrow (2),
+                                // badge + space (2), padding (2). Defensive floor at 8 chars.
+                                const pathBudget = Math.max(8, MULTI_FILE_DIFF_LEFT_WIDTH - 4 - 2 - 2);
+                                return (_jsxs(Box, { children: [_jsx(Text, { color: isHighlighted ? 'cyan' : undefined, bold: isHighlighted, children: isHighlighted ? '▸ ' : '  ' }), _jsx(Text, { color: badgeColor, dimColor: badgeDim, bold: !badgeDim, children: `${badgeGlyph} ` }), _jsx(Text, { color: isHighlighted ? 'cyan' : undefined, bold: isHighlighted, children: truncateMiddle(entry.path, pathBudget) }), entry.hint !== undefined && entry.hint.length > 0 ? (_jsx(Text, { dimColor: true, italic: true, children: ` (${entry.hint})` })) : null] }, `file-${idx}-${entry.path}`));
+                            })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, flexGrow: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, dimColor: true, children: diffPaneTitle }), activeLines.length > paneHeight ? (_jsx(Text, { dimColor: true, children: ` · lines ${scrollOffset + 1}-${Math.min(scrollOffset + paneHeight, activeLines.length)}/${activeLines.length}` })) : null] }), visibleLines.length === 0 ? (_jsx(Text, { dimColor: true, italic: true, children: '(empty diff)' })) : (visibleLines.map((line, idx) => {
+                                const kind = classifyDiffLine(line);
+                                const rp = renderProps(kind);
+                                return (_jsx(Text, { color: rp.color, bold: rp.bold, dimColor: rp.dimColor, children: line.length > 0 ? line : ' ' }, `diff-${cursor}-${scrollOffset + idx}`));
+                            }))] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "green", children: `${approvedCount}/${total} approved` }), _jsx(Text, { dimColor: true, children: ' · ' }), _jsx(Text, { color: "red", children: `${rejectedCount}/${total} rejected` }), _jsx(Text, { dimColor: true, children: ' · ' }), _jsx(Text, { children: `${pendingCount} remaining` }), _jsx(Text, { dimColor: true, children: ' · Enter when done' })] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '[↑↓] navigate  ·  [a] approve  ·  [r] reject  ·  [A] all  ·  [R] none  ·  [PgUp/PgDn] scroll  ·  [Esc] cancel' }) })] })] }));
+}
+//# sourceMappingURL=multi-file-diff-approval.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.90",
+  "version": "0.1.0-beta.91",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -63,7 +63,7 @@
     "which": "^6.0.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.90"
+    "@pugi/sdk": "0.1.0-beta.91"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",