@pugi/cli 0.1.0-beta.93 → 0.1.0-beta.95

package/dist/core/retro/plane-collector.js

@@ -0,0 +1,274 @@
+/**
+ * Plane REST client for `pugi retro`.
+ *
+ * Read-only by default — lists closed + created issues, cycles, and
+ * modules in the configured project. `postRetroToPlane` is the only
+ * mutating surface and is gated by --post-plane.
+ *
+ * Config is read from `.pugi/settings.json` + env (precedence: env
+ * overrides settings). The REST shape mirrors the admin-api's
+ * PlaneService: `X-API-Key: <token>` header, `redirect: 'manual'` so
+ * a malicious 3xx never carries the token to an attacker-chosen host.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SETTINGS_REL = '.pugi/settings.json';
+const DEFAULT_BASE_URL = 'https://plane.pugi.io';
+const DEFAULT_WORKSPACE = 'pugi-customers';
+/** Marker embedded into every retro post so we can detect a prior
+ * post for the same date+seq and short-circuit to idempotent. */
+export function buildRetroMarker(dateLabel, sequence) {
+    return `pugi-retro-id: ${dateLabel}-${sequence}`;
+}
+export function resolvePlaneConfig(root, env = process.env) {
+    const settings = readSettings(root);
+    const baseUrl = (env.PLANE_BASE_URL ?? settings.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const apiKey = env.PLANE_API_KEY ?? settings.apiKey ?? '';
+    const workspaceSlug = env.PLANE_WORKSPACE_SLUG ?? settings.workspaceSlug ?? DEFAULT_WORKSPACE;
+    const projectId = env.PLANE_PROJECT_ID ?? settings.projectId ?? '';
+    if (!apiKey) {
+        return { ok: false, reason: 'PLANE_API_KEY not configured' };
+    }
+    if (!projectId) {
+        return { ok: false, reason: 'PLANE_PROJECT_ID not configured' };
+    }
+    return {
+        ok: true,
+        config: { baseUrl, apiKey, workspaceSlug, projectId },
+    };
+}
+function readSettings(root) {
+    const path = join(root, SETTINGS_REL);
+    if (!existsSync(path))
+        return {};
+    try {
+        const body = JSON.parse(readFileSync(path, 'utf8'));
+        const plane = body.plane;
+        if (!plane || typeof plane !== 'object')
+            return {};
+        const slice = plane;
+        const baseUrl = typeof slice.baseUrl === 'string' ? slice.baseUrl : undefined;
+        const apiKey = typeof slice.apiKey === 'string' ? slice.apiKey : undefined;
+        const workspaceSlug = typeof slice.workspaceSlug === 'string' ? slice.workspaceSlug : undefined;
+        const projectId = typeof slice.projectId === 'string' ? slice.projectId : undefined;
+        return { baseUrl, apiKey, workspaceSlug, projectId };
+    }
+    catch {
+        return {};
+    }
+}
+async function planeRequest(config, path, init, fetchImpl) {
+    const url = `${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    const headers = {
+        'X-API-Key': config.apiKey,
+        Accept: 'application/json',
+    };
+    if (init.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const merged = {
+        ...init,
+        headers: { ...headers, ...init.headers },
+        // Mirror admin-api PlaneService — never auto-follow redirects so a
+        // compromised upstream cannot redirect us with the API key in tow.
+        redirect: 'manual',
+    };
+    const res = await fetchImpl(url, merged);
+    if (res.status >= 300 && res.status < 400) {
+        throw new Error(`plane_unexpected_redirect_${res.status}`);
+    }
+    if (!res.ok) {
+        // P1 (triple-review 2026-06-04, ): never echo upstream body.
+        // It may contain the API key if the operator misconfigured the URL
+        // with a query-string token, or any future Plane request-id header
+        // that surfaces the bearer. Generic shape only.
+        throw new Error(`plane_upstream_${res.status}`);
+    }
+    if (res.status === 204) {
+        // P3 → P1 (triple-review 2026-06-04 round 2): 204 has two meanings.
+        // On GET = empty collection → return []. On POST/PATCH = no body
+        // returned, but `postRetroToPlane` requires the created resource id
+        // back, so casting `[]` to a single `RawPlaneIssue` and reading
+        // `.id` would silently produce `''` and break idempotency. Throw
+        // when 204 lands on a mutation method instead.
+        const method = (init.method ?? 'GET').toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD') {
+            throw new Error(`plane_unexpected_204_on_${method.toLowerCase()}`);
+        }
+        return [];
+    }
+    return (await res.json());
+}
+async function listIssues(config, query, fetchImpl) {
+    const out = [];
+    let path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/issues/${query}`;
+    while (path) {
+        const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+        if (Array.isArray(page)) {
+            out.push(...page);
+            path = undefined;
+        }
+        else {
+            out.push(...(page.results ?? []));
+            // We do not support cross-host pagination here (admin-api does); for
+            // retros, the first page is sufficient at our typical issue counts.
+            path = undefined;
+        }
+    }
+    return out;
+}
+function toIssueRef(raw, statesById) {
+    const stateId = raw.state_id ?? raw.state;
+    const state = stateId ? statesById.get(stateId) : undefined;
+    return {
+        id: raw.id ?? '',
+        sequenceId: typeof raw.sequence_id === 'number' ? raw.sequence_id : 0,
+        name: raw.name ?? '',
+        stateId,
+        stateName: state?.name,
+        stateGroup: state?.group,
+        createdAt: raw.created_at,
+        completedAt: raw.completed_at ?? undefined,
+    };
+}
+async function listStates(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/states/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+async function listCycles(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/cycles/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+async function listModules(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/modules/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+function pickActiveCycle(cycles, now) {
+    const nowMs = now.getTime();
+    let chosen;
+    for (const c of cycles) {
+        if (!c.start_date || !c.end_date)
+            continue;
+        const start = Date.parse(c.start_date);
+        const end = Date.parse(c.end_date);
+        if (!Number.isFinite(start) || !Number.isFinite(end))
+            continue;
+        if (start <= nowMs && nowMs <= end) {
+            chosen = c;
+            break;
+        }
+    }
+    if (!chosen)
+        return undefined;
+    const total = chosen.total_issues ?? 0;
+    const completed = chosen.completed_issues ?? 0;
+    const progressPercent = total === 0 ? 0 : Math.round((completed / total) * 100);
+    return {
+        id: chosen.id ?? '',
+        name: chosen.name ?? '',
+        startDate: chosen.start_date,
+        endDate: chosen.end_date,
+        progressPercent,
+    };
+}
+export async function collectPlaneSlice(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const sinceIso = options.since.toISOString();
+    const states = await listStates(options.config, fetchImpl);
+    const statesById = new Map();
+    for (const s of states)
+        if (s.id)
+            statesById.set(s.id, s);
+    const [closedRaw, createdRaw, cyclesRaw, modulesRaw] = await Promise.all([
+        listIssues(options.config, `?state__group=completed&completed_at__gte=${encodeURIComponent(sinceIso)}`, fetchImpl),
+        listIssues(options.config, `?created_at__gte=${encodeURIComponent(sinceIso)}`, fetchImpl),
+        listCycles(options.config, fetchImpl),
+        listModules(options.config, fetchImpl),
+    ]);
+    const closedIssues = closedRaw.map((r) => toIssueRef(r, statesById));
+    const createdIssues = createdRaw.map((r) => toIssueRef(r, statesById));
+    const modules = modulesRaw.map((m) => ({
+        id: m.id ?? '',
+        name: m.name ?? '',
+        issueCount: m.total_issues ?? 0,
+    }));
+    const activeCycle = pickActiveCycle(cyclesRaw, new Date());
+    return {
+        closedIssues,
+        createdIssues,
+        activeCycle,
+        modules,
+        oversizedModules: [],
+        prToIssueLinks: [],
+        sprintVelocity: {
+            closedCount: closedIssues.length,
+            createdCount: createdIssues.length,
+            netDelta: closedIssues.length - createdIssues.length,
+        },
+    };
+}
+/** Pick a state in the `backlog` group so the post lands in the right
+ * column. Falls back to the first available state if no backlog state
+ * is found (Plane lets operators rename groups, but `group=backlog`
+ * is the canonical default).
+ */
+async function pickBacklogStateId(config, fetchImpl) {
+    const states = await listStates(config, fetchImpl);
+    const backlog = states.find((s) => s.group === 'backlog');
+    if (backlog?.id)
+        return backlog.id;
+    const first = states[0];
+    return first?.id;
+}
+export async function postRetroToPlane(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const marker = buildRetroMarker(options.dateLabel, options.sequence);
+    const issueName = `Retro ${options.dateLabel} (seq ${options.sequence})`;
+    // Idempotency probe: list recent issues, look for the marker in
+    // description_html or the canonical issue name.
+    const recent = await listIssues(options.config, `?name__icontains=${encodeURIComponent(`Retro ${options.dateLabel}`)}`, fetchImpl);
+    for (const raw of recent) {
+        const haystack = `${raw.name ?? ''}\n${raw.description_html ?? ''}`;
+        if (haystack.includes(marker)) {
+            return {
+                url: buildIssueUrl(options.config, raw.id ?? ''),
+                issueId: raw.id ?? '',
+                alreadyExists: true,
+            };
+        }
+    }
+    const stateId = await pickBacklogStateId(options.config, fetchImpl);
+    const descriptionHtml = `<!-- ${marker} -->\n<pre>${escapeHtml(options.markdown)}</pre>`;
+    const body = {
+        name: issueName,
+        description_html: descriptionHtml,
+        priority: 'none',
+    };
+    if (stateId)
+        body.state = stateId;
+    const created = await planeRequest(options.config, `/workspaces/${options.config.workspaceSlug}/projects/${options.config.projectId}/issues/`, { method: 'POST', body: JSON.stringify(body) }, fetchImpl);
+    return {
+        url: buildIssueUrl(options.config, created.id ?? ''),
+        issueId: created.id ?? '',
+        alreadyExists: false,
+    };
+}
+function buildIssueUrl(config, issueId) {
+    return `${config.baseUrl}/${config.workspaceSlug}/projects/${config.projectId}/issues/${issueId}`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=plane-collector.js.map

package/dist/core/retro/pr-issue-link.js

@@ -0,0 +1,65 @@
+/**
+ * PR-to-issue link extractor for `pugi retro`.
+ *
+ * Walks the harvested commits and matches `[A-Z]+-\d+` markers in
+ * subject + body — same shape as the existing admin-api state-sync
+ * cron uses for `PUGI-N` matches. Enrichment joins the matched ref
+ * against the Plane issue collection (when --plane is on) so the
+ * narrative can show "PR ↔ issue" pairs.
+ */
+const ISSUE_REF_RE = /\b([A-Z][A-Z0-9]*-\d+)\b/g;
+/** Extract every `<PREFIX>-<NUM>` token from a haystack. Order is
+ * preserved (first occurrence wins); duplicates collapse.
+ */
+export function extractIssueRefs(haystack) {
+    const out = [];
+    const seen = new Set();
+    ISSUE_REF_RE.lastIndex = 0;
+    let m;
+    while ((m = ISSUE_REF_RE.exec(haystack)) !== null) {
+        const ref = m[1];
+        if (!ref)
+            continue;
+        if (seen.has(ref))
+            continue;
+        seen.add(ref);
+        out.push(ref);
+    }
+    return out;
+}
+/** Build PR-to-issue links from a commit list. When `issues` is
+ * empty the links carry `planeIssue: undefined`; this lets the
+ * renderer surface the refs even without Plane enrichment.
+ */
+export function enrichLinks(commits, issues) {
+    // Build a quick lookup from sequenceId + project-prefix to PlaneIssueRef.
+    // We don't know the project's identifier here, so we match by the
+    // numeric tail of `<PREFIX>-<seq>` against `issue.sequenceId`.
+    const bySequence = new Map();
+    for (const issue of issues) {
+        bySequence.set(issue.sequenceId, issue);
+    }
+    const links = [];
+    const seen = new Set();
+    for (const commit of commits) {
+        const haystack = `${commit.subject}\n${commit.body}`;
+        const refs = extractIssueRefs(haystack);
+        for (const ref of refs) {
+            const dedupeKey = `${commit.sha}:${ref}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            const tailMatch = /-(\d+)$/.exec(ref);
+            const seq = tailMatch ? Number.parseInt(tailMatch[1] ?? '0', 10) : NaN;
+            const planeIssue = Number.isFinite(seq) ? bySequence.get(seq) : undefined;
+            links.push({
+                prSha: commit.sha,
+                prSubject: commit.subject,
+                issueRef: ref,
+                planeIssue,
+            });
+        }
+    }
+    return links;
+}
+//# sourceMappingURL=pr-issue-link.js.map

package/dist/core/retro/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared types for `pugi retro` — engineering retrospective command.
+ *
+ * The retro pipeline runs in three stages:
+ *   1. Git collection (git-collector.ts) → RawCommit[]
+ *   2. Metric aggregation (metrics.ts) → RetroMetrics
+ *   3. Render + persist (narrative.ts) → markdown + JSON snapshot
+ *
+ * Optional Plane enrichment (plane-collector.ts) populates a PlaneSlice
+ * which the renderer joins onto the markdown if --plane was passed.
+ *
+ * All timestamps are ISO 8601 strings. Numeric fields default to 0
+ * (never undefined) so the renderer never branches on absence.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/sandboxing/adapter.js

@@ -0,0 +1,29 @@
+/**
+ * Bash sandbox adapter interface (Trust Sprint item 6).
+ *
+ * Adapter pattern so the bash tool stays unchanged: a runner wraps the
+ * spawn invocation with an OS-level sandbox primitive. Today's variants:
+ *
+ *   - none           — passthrough (existing behaviour).
+ *   - macOS-seatbelt — /usr/bin/sandbox-exec with a workspace-scoped
+ *                      write allowlist, read-anywhere, network-allow
+ *                      profile.
+ *   - docker         — Linux fallback. Throws at boot (deferred to a
+ *                      follow-up PR; schema accepts the keyword so
+ *                      operators can see it documented).
+ *
+ * The CLI bash tool itself is owned by a parallel agent (PUGI-VERIFY-
+ * GATE). We intentionally do NOT modify `tools/bash.ts` here. Instead
+ * the sandbox sits as an indirection layer between higher-level
+ * callers (`runtime/cli.ts`, `core/bash-runner.ts` if introduced
+ * later) and the existing bash entry-point.
+ *
+ * Future: replace this with native landlock bindings on Linux and
+ * job-object on Windows. The interface is stable, the adapters
+ * change.
+ */
+export {};
+// The `makeAdapter` resolver lives in `./index.ts` so it can import
+// the concrete adapters via ESM without circular references. This
+// file stays pure interfaces.
+//# sourceMappingURL=adapter.js.map

package/dist/core/sandboxing/index.js

@@ -0,0 +1,49 @@
+/**
+ * Sandbox adapter resolver (Trust Sprint item 6).
+ *
+ * Single re-export surface so consumers (`pugi doctor`, future bash
+ * runner indirection, MCP serve diagnostics) can do:
+ *
+ *   import { makeAdapter, type SandboxMode } from '.../sandboxing';
+ *
+ * The concrete adapters live in sibling files; this index wires the
+ * lookup table without forcing a circular import between the
+ * interface (`adapter.ts`) and the implementations.
+ */
+import { NoneSandboxAdapter } from './none.js';
+import { SeatbeltSandboxAdapter } from './seatbelt.js';
+export { NoneSandboxAdapter } from './none.js';
+export { SeatbeltSandboxAdapter } from './seatbelt.js';
+/**
+ * Resolve a sandbox adapter from a configured mode. Throws for
+ * `docker` (documented but not shipped in this PR) and for unknown
+ * modes (defends against forward-rolled settings.json files).
+ */
+export function makeAdapter(mode) {
+    switch (mode) {
+        case 'none':
+            return new NoneSandboxAdapter();
+        case 'macOS-seatbelt':
+            return new SeatbeltSandboxAdapter();
+        case 'docker':
+            throw new Error('bash sandbox: docker mode is documented but not yet implemented. ' +
+                'Use bash.sandbox = "none" or "macOS-seatbelt" until the docker adapter ships.');
+        default: {
+            const exhaustive = mode;
+            throw new Error(`bash sandbox: unknown mode "${String(exhaustive)}"`);
+        }
+    }
+}
+/**
+ * Convenience: probe the configured mode without spawning anything.
+ * Used by `pugi doctor` so the sandbox probe can report the same
+ * armed state the bash runner would see.
+ */
+export function probeSandbox(opts) {
+    const adapter = makeAdapter(opts.mode);
+    return adapter.probe({
+        workspaceRoot: opts.workspaceRoot,
+        ...(opts.extraWritePaths ? { extraWritePaths: opts.extraWritePaths } : {}),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/core/sandboxing/none.js

@@ -0,0 +1,19 @@
+export class NoneSandboxAdapter {
+    mode = 'none';
+    probe(_opts) {
+        return {
+            mode: 'none',
+            armed: false,
+            reason: "policy 'none' selected — bash dispatches run unsandboxed (classifier + permission FSM still apply).",
+            details: ['mode: none (passthrough)', 'enforcement: bash classifier + permission FSM only'],
+        };
+    }
+    wrap(cmd, _opts) {
+        return {
+            command: cmd.command,
+            args: cmd.args,
+            description: 'sandbox: none (passthrough)',
+        };
+    }
+}
+//# sourceMappingURL=none.js.map

package/dist/core/sandboxing/seatbelt.js

@@ -0,0 +1,183 @@
+/**
+ * macOS Seatbelt sandbox adapter (Trust Sprint item 6).
+ *
+ * Wraps bash command execution with `/usr/bin/sandbox-exec` and a
+ * dynamically-generated profile. Policy posture:
+ *
+ *   - Reads ANYWHERE (so `node_modules` lookups, system headers,
+ *     package indices etc all keep working).
+ *   - Writes ALLOWED under: workspaceRoot, ~/.pugi/, and any
+ *     additional paths the caller explicitly passes (typical: /tmp,
+ *     plus the resolved pnpm cache dir if it lives outside ~/.pugi).
+ *   - Process execution ALLOWED (we need to spawn child binaries to
+ *     run pnpm / git / etc).
+ *   - Network egress ALLOWED (npm install, git fetch, web fetch).
+ *
+ * Profile is rendered to a tmp file per `wrap()` call. The temp file
+ * lives in OS tmpdir with mode 0o600. We do NOT cache the profile
+ * because workspaceRoot or extraWritePaths can vary per call (e.g.
+ * REPL working-directory changes); the file write is cheap.
+ *
+ * Cancel-cleanup: profile temp files are written with the process
+ * pid + random suffix so concurrent calls don't collide. We leave
+ * cleanup to the kernel's tmp reaper rather than tracking handles
+ * inside the adapter — adding ref-counting would couple the sandbox
+ * lifecycle to the bash runner and `pugi mcp serve`, both of which
+ * are owned by other agents.
+ *
+ * Security note: sandbox-exec's profile language is best-effort. It
+ * is not a kernel-enforced jail. The intent here is to catch
+ * accidental writes outside the workspace (e.g. a renamed test that
+ * accidentally writes to $HOME), not to harden against a determined
+ * attacker who controls the spawned binary.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+const SANDBOX_EXEC_PATH = '/usr/bin/sandbox-exec';
+export class SeatbeltSandboxAdapter {
+    mode = 'macOS-seatbelt';
+    probe(opts) {
+        if (process.platform !== 'darwin') {
+            return {
+                mode: 'macOS-seatbelt',
+                armed: false,
+                reason: `macOS-seatbelt unavailable on ${process.platform} — choose 'none' or 'docker'.`,
+                details: [`platform: ${process.platform}`, `expected: darwin`],
+            };
+        }
+        if (!sandboxExecBinaryAvailable()) {
+            return {
+                mode: 'macOS-seatbelt',
+                armed: false,
+                reason: `sandbox-exec not callable at ${SANDBOX_EXEC_PATH}.`,
+                details: [
+                    `binary: ${SANDBOX_EXEC_PATH}`,
+                    'remediation: verify Apple has not deprecated the binary on this macOS major.',
+                ],
+            };
+        }
+        return {
+            mode: 'macOS-seatbelt',
+            armed: true,
+            details: [
+                'platform: darwin',
+                `binary: ${SANDBOX_EXEC_PATH}`,
+                `workspaceRoot: ${opts.workspaceRoot}`,
+                `extraWritePaths: ${(opts.extraWritePaths ?? []).join(', ') || '<none>'}`,
+            ],
+        };
+    }
+    wrap(cmd, opts) {
+        const armed = this.probe(opts);
+        if (!armed.armed) {
+            throw new Error(`SeatbeltSandboxAdapter.wrap: ${armed.reason}`);
+        }
+        if (!isAbsolute(opts.workspaceRoot)) {
+            throw new Error(`SeatbeltSandboxAdapter.wrap: workspaceRoot must be absolute, got "${opts.workspaceRoot}"`);
+        }
+        for (const p of opts.extraWritePaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`SeatbeltSandboxAdapter.wrap: extraWritePaths entry must be absolute, got "${p}"`);
+            }
+        }
+        const profilePath = writeProfileFile(opts);
+        return {
+            command: SANDBOX_EXEC_PATH,
+            args: ['-f', profilePath, cmd.command, ...cmd.args],
+            description: `sandbox: macOS-seatbelt (profile=${profilePath})`,
+        };
+    }
+    /**
+     * Render the Seatbelt profile (TCL/Lisp-ish) for the given write
+     * allowlist. Exposed for unit tests; the live wrap path uses
+     * `writeProfileFile` internally.
+     */
+    renderProfile(opts) {
+        return renderProfile(opts);
+    }
+}
+function sandboxExecBinaryAvailable() {
+    try {
+        // `sandbox-exec` exits non-zero with a usage banner on `-h`. We
+        // capture the banner via stderr and accept any rapid exit as
+        // evidence the binary is callable.
+        execFileSync(SANDBOX_EXEC_PATH, ['-h'], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+            timeout: 3000,
+        });
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        // ENOENT means the binary itself is missing. A non-zero exit code
+        // (sandbox-exec usage banner) is success for our purposes.
+        if (e?.code === 'ENOENT')
+            return false;
+        return true;
+    }
+}
+function writeProfileFile(opts) {
+    const profile = renderProfile(opts);
+    const dir = mkdtempSync(join(tmpdir(), 'pugi-seatbelt-'));
+    const path = join(dir, 'profile.sb');
+    writeFileSync(path, profile, { mode: 0o600 });
+    return path;
+}
+/**
+ * Generate the Seatbelt profile. Keep the language tight:
+ *
+ *   - (version 1) — required header.
+ *   - (deny default) — start from no permissions.
+ *   - (allow process*) — allow spawning child processes.
+ *   - (allow file-read*) — reads unrestricted.
+ *   - (allow file-write* (subpath "...")) — writes scoped.
+ *   - (allow network*) — egress unrestricted.
+ *   - (allow signal) + sysctl-read for normal node operation.
+ */
+function renderProfile(opts) {
+    const writePaths = [opts.workspaceRoot, ...(opts.extraWritePaths ?? [])];
+    const writeRules = writePaths
+        .map((p) => `  (subpath ${quoteForSeatbelt(p)})`)
+        .join('\n');
+    // Devices required for normal stdout/stderr piping. /dev/null is
+    // table stakes; pts/* keeps interactive PTY-based tools (pagers,
+    // editors) working when an operator runs them under the sandbox.
+    const devicePaths = ['/dev/null', '/dev/dtracehelper', '/dev/tty', '/dev/stdout', '/dev/stderr'];
+    const deviceRules = devicePaths
+        .map((p) => `  (literal ${quoteForSeatbelt(p)})`)
+        .join('\n');
+    return [
+        '(version 1)',
+        '(deny default)',
+        '(allow process-exec)',
+        '(allow process-fork)',
+        '(allow signal (target self))',
+        '(allow sysctl-read)',
+        '(allow file-read*)',
+        '(allow file-write*',
+        writeRules,
+        ')',
+        '(allow file-write*',
+        deviceRules,
+        ')',
+        '(allow network*)',
+        '(allow mach-lookup)',
+        '(allow ipc-posix-shm)',
+        '',
+    ].join('\n');
+}
+/**
+ * Seatbelt profile string literals use TCL-style double-quoted
+ * strings. We need to escape `"` and `\` but the profile language
+ * does not accept arbitrary control chars; reject any input that
+ * contains them so we never silently emit a malformed profile.
+ */
+function quoteForSeatbelt(value) {
+    if (/[\x00-\x1f"\\]/.test(value)) {
+        throw new Error(`SeatbeltSandboxAdapter: refusing to render profile with non-printable or quote chars in "${value}"`);
+    }
+    return `"${value}"`;
+}
+//# sourceMappingURL=seatbelt.js.map

package/dist/core/session.js

@@ -16,8 +16,35 @@ export function openSession(root) {
         pugiDir,
         eventsPath,
         enabled,
+        verificationLedger: [],
     };
 }
+/**
+ * PUGI-VERIFY-GATE — append a verification ledger entry. Mutates
+ * `session.verificationLedger` in place AND mirrors the entry to
+ * the JSONL audit log when the session is enabled. Pure helper
+ * (no I/O on disabled sessions); safe to call from sync code
+ * paths.
+ *
+ * The bash tool dispatcher calls this after every shell exec whose
+ * head matches a `VERIFICATION_PATTERNS` entry.
+ */
+export function recordVerificationCall(session, entry) {
+    session.verificationLedger.push(entry);
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'verification',
+        name: 'call_recorded',
+        tool: entry.tool,
+        command: entry.command,
+        exitCode: entry.exitCode,
+        tailStderrLen: entry.tailStderr.length,
+    }, session.eventsPath);
+}
 /**
  * MVP — fire the `SessionStart` lifecycle event for all hooks
  * declared in `~/.pugi/hooks-mvp.json`. Single-call surface; the REPL