pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/runtime/lock.js

@@ -0,0 +1,123 @@
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+const DEFAULT_STALE_MS = 15 * 60_000;
+function identity(path) {
+    try {
+        const st = lstatSync(path);
+        return { dev: st.dev, ino: st.ino };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function sameIdentity(a, b) {
+    return Boolean(b && a.dev === b.dev && a.ino === b.ino);
+}
+export class FileLock {
+    fd;
+    owner;
+    heldIdentity;
+    path;
+    staleMs;
+    constructor(path, staleMs = DEFAULT_STALE_MS) { this.path = path; this.staleMs = staleMs; }
+    acquire() {
+        if (this.fd !== undefined)
+            return true;
+        mkdirSync(dirname(this.path), { recursive: true });
+        this.clearStale();
+        let fd;
+        try {
+            fd = openSync(this.path, "wx", 0o600);
+        }
+        catch (error) {
+            const code = error.code;
+            // Windows can report EPERM while another process's deleted lock is still pending removal.
+            // Treat it as contention; callers already impose a bounded retry or return busy.
+            if (code === "EEXIST" || (process.platform === "win32" && code === "EPERM"))
+                return false;
+            throw error;
+        }
+        const owner = randomUUID();
+        const stat = fstatSync(fd);
+        const held = { dev: stat.dev, ino: stat.ino };
+        try {
+            writeFileSync(fd, JSON.stringify({ pid: process.pid, owner, at: new Date().toISOString() }));
+            this.fd = fd;
+            this.owner = owner;
+            this.heldIdentity = held;
+            return true;
+        }
+        catch (error) {
+            closeSync(fd);
+            if (sameIdentity(held, identity(this.path)))
+                unlinkSync(this.path);
+            throw error;
+        }
+    }
+    release() {
+        // A failed contender never owns the lock, and must not unlink another owner's file.
+        if (this.fd === undefined || !this.owner || !this.heldIdentity)
+            return;
+        const held = this.heldIdentity;
+        const owner = this.owner;
+        try {
+            if (sameIdentity(held, identity(this.path))) {
+                const onDisk = JSON.parse(readFileSync(this.path, "utf8"));
+                if (onDisk.owner === owner && sameIdentity(held, identity(this.path)))
+                    unlinkSync(this.path);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        finally {
+            closeSync(this.fd);
+            this.fd = undefined;
+            this.owner = undefined;
+            this.heldIdentity = undefined;
+        }
+    }
+    clearStale() {
+        const initial = identity(this.path);
+        if (!initial)
+            return;
+        try {
+            const raw = readFileSync(this.path, "utf8");
+            const pid = Number(JSON.parse(raw).pid);
+            if (Number.isSafeInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                    return; // Live owner, even when older than the stale threshold.
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code !== "ESRCH")
+                        return; // EPERM and unknown failures do not prove death.
+                    if (sameIdentity(initial, identity(this.path)))
+                        unlinkSync(this.path); // Dead owner.
+                    return;
+                }
+            }
+            // Incomplete lock creation or a malformed legacy lock: apply a conservative age limit.
+            const age = Date.now() - statSync(this.path).mtimeMs;
+            if (age >= this.staleMs && sameIdentity(initial, identity(this.path)))
+                unlinkSync(this.path);
+        }
+        catch { /* Concurrent lock modification: fail closed. */ }
+    }
+}
+export async function withFileLock(path, fn) {
+    const lock = new FileLock(path);
+    if (!lock.acquire())
+        throw new Error(`Resource is locked: ${path}`);
+    try {
+        return await fn();
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/runtime/migrate.d.ts

@@ -0,0 +1,9 @@
+export declare function migrate(dryRun?: boolean): {
+    dryRun: boolean;
+    records: {
+        id: string;
+        path: string;
+        needsMigration: boolean;
+    }[];
+    backup?: string;
+};

package/dist/runtime/migrate.js

@@ -0,0 +1,44 @@
+import { FileLock } from "./lock.js";
+import { lockPath } from "./home.js";
+import { copyFileSync, mkdirSync, readdirSync, readFileSync, existsSync } from 'node:fs';
+import { homePath } from "./home.js";
+import { writeJsonAtomic } from "./store.js";
+export function migrate(dryRun = true) {
+    const records = [];
+    for (const kind of ['workflows', 'agents']) {
+        const dir = homePath(kind);
+        if (!existsSync(dir))
+            continue;
+        for (const file of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+            const path = homePath(kind, file);
+            const r = JSON.parse(readFileSync(path, 'utf8'));
+            if (!r.id)
+                throw new Error(`STATE_UNCERTAIN: ${file}`);
+            records.push({ id: r.id, path, needsMigration: r.schemaVersion !== 2 });
+        }
+    }
+    if (dryRun)
+        return { dryRun, records };
+    const backup = homePath('backups', String(Date.now()));
+    mkdirSync(backup, { recursive: true });
+    for (const r of records.filter(r => r.needsMigration)) {
+        const kind = r.path.includes('/workflows/') ? 'workflow' : 'agent';
+        const lock = new FileLock(lockPath(`state-${kind}-${r.id}`));
+        if (!lock.acquire())
+            throw new Error('MIGRATION_BUSY');
+        try {
+            const value = JSON.parse(readFileSync(r.path, 'utf8'));
+            if (['running', 'cancelling'].includes(value.state))
+                throw new Error('MIGRATION_REQUIRES_QUIESCENT_STORE');
+            copyFileSync(r.path, `${backup}/${r.id}.json`);
+            value.schemaVersion = 2;
+            if (value.calls)
+                value.verification = 'unknown';
+            writeJsonAtomic(r.path, value);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    return { dryRun, records, backup };
+}

package/dist/runtime/ownership.d.ts

@@ -0,0 +1,4 @@
+/** Tool and command entrypoints must not expose another Pi session's durable records. */
+export declare function assertSessionOwner(record: {
+    parentSessionId?: string;
+} | undefined, sessionId: string): void;

package/dist/runtime/ownership.js

@@ -0,0 +1,6 @@
+/** Tool and command entrypoints must not expose another Pi session's durable records. */
+export function assertSessionOwner(record, sessionId) {
+    if (!record || !record.parentSessionId || record.parentSessionId !== sessionId) {
+        throw new Error("Record not found in this Pi session.");
+    }
+}

package/dist/runtime/protocol.d.ts

@@ -0,0 +1,24 @@
+import type { Artifact, Evidence, Ledger, TaskBrief, Event } from '../contracts/types.js';
+import type { DispatchRecord } from './types.js';
+export declare const hash: (value: unknown) => string;
+export declare const uid: (prefix: string) => string;
+export interface ProtocolState {
+    schemaVersion: 1;
+    revision: number;
+    artifacts: Record<string, Artifact>;
+    evidence: Record<string, Evidence>;
+    ledgers: Record<string, Ledger>;
+    briefs: Record<string, TaskBrief[]>;
+    invalidations: Record<string, {
+        at: string;
+        reason: string;
+    }>;
+    programs: Record<string, any>;
+    frontiers: Record<string, any>;
+    approvals: Record<string, any>;
+    leases: Record<string, any>;
+    events: Event[];
+    dispatches: Record<string, DispatchRecord>;
+}
+export declare function protocol(): ProtocolState;
+export declare function transact<T>(type: string, subject: string, actor: string, fn: (state: ProtocolState) => T): T;

package/dist/runtime/protocol.js

@@ -0,0 +1,35 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { homePath, lockPath } from "./home.js";
+import { FileLock } from "./lock.js";
+import { writeJsonAtomic } from "./store.js";
+export const hash = (value) => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+export const uid = (prefix) => `${prefix}_${randomUUID().replaceAll('-', '')}`;
+const empty = () => ({ schemaVersion: 1, revision: 0, artifacts: {}, evidence: {}, ledgers: {}, briefs: {}, invalidations: {}, programs: {}, frontiers: {}, approvals: {}, leases: {}, events: [], dispatches: {} });
+export function protocol() {
+    const path = homePath('protocol.json');
+    if (!existsSync(path))
+        return empty();
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state.schemaVersion !== 1 || !state.ledgers || !state.artifacts || !Array.isArray(state.events))
+        throw new Error('STATE_UNCERTAIN: invalid protocol store');
+    state.dispatches ??= {};
+    return state;
+}
+// State and audit events commit in one atomic envelope. No cross-file journal transaction claims.
+export function transact(type, subject, actor, fn) {
+    const lock = new FileLock(lockPath('protocol-state'));
+    if (!lock.acquire())
+        throw new Error('STATE_BUSY: retry protocol operation');
+    try {
+        const state = protocol();
+        const result = fn(state);
+        state.revision++;
+        state.events.push({ id: uid('evt'), at: new Date().toISOString(), actor, type, subject, data: result ?? null });
+        writeJsonAtomic(homePath('protocol.json'), state);
+        return result;
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/runtime/redact.d.ts

@@ -0,0 +1,3 @@
+export declare function redactSecrets(text: string): string;
+/** Redacts the whole buffer first, so a secret split across chunks is still whole when matched. */
+export declare function redactLogTail(raw: string, cap: number): string;

package/dist/runtime/redact.js

@@ -0,0 +1,32 @@
+const LABELS = [
+    "authorization", "proxy-authorization", "api[_-]?key", "apikey",
+    "access[_-]?token", "auth[_-]?token", "refresh[_-]?token", "id[_-]?token",
+    "token", "password", "passwd", "secret", "client[_-]?secret", "private[_-]?key",
+].join("|");
+const PREFIXES = [
+    "github_pat_", "ghp_", "gho_", "ghu_", "ghs_", "ghr_",
+    "glpat-", "glsa_", "gldt-", "npm_", "pypi-", "hf_",
+    "xoxb-", "xoxp-", "xoxa-", "xoxr-", "xoxs-", "xapp-",
+    "shpat_", "shpss_", "sk-ant-", "sk_live_", "sk_test_", "sk-", "AIza", "AKIA", "ASIA",
+].join("|");
+const RULES = [
+    { pattern: new RegExp(`((?:${LABELS})\\s*[:=]\\s*(?:[Bb]earer\\s+)?)("[^"]*"|'[^']*'|[^\\s,"'}]+)`, "gi"), replace: "$1[REDACTED]" },
+    { pattern: /([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s/@]+@/g, replace: "$1[REDACTED]@" },
+    { pattern: new RegExp(`(?:${PREFIXES})[A-Za-z0-9_-]{8,}`, "g"), replace: "[REDACTED]" },
+    { pattern: /\bBearer\s+[A-Za-z0-9._~+/-]{8,}=*/g, replace: "Bearer [REDACTED]" },
+];
+export function redactSecrets(text) {
+    let result = text;
+    for (const rule of RULES)
+        result = result.replace(rule.pattern, rule.replace);
+    return result;
+}
+/** Redacts the whole buffer first, so a secret split across chunks is still whole when matched. */
+export function redactLogTail(raw, cap) {
+    const redacted = redactSecrets(raw);
+    if (raw.length <= cap)
+        return redacted;
+    const tail = redacted.slice(-cap);
+    const firstBreak = tail.indexOf("\n");
+    return firstBreak >= 0 ? tail.slice(firstBreak + 1) : tail;
+}

package/dist/runtime/store.d.ts

@@ -0,0 +1,6 @@
+export declare function ensureHome(): void;
+export declare function readJson<T>(path: string, fallback: T): T;
+export declare function writeJsonAtomic(path: string, value: unknown): void;
+export declare function appendJournal(path: string, event: unknown): void;
+export declare function listJson<T>(dir: string): T[];
+export declare function removeFile(path: string): void;

package/dist/runtime/store.js

@@ -0,0 +1,75 @@
+import { closeSync, fsyncSync, openSync, appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pstackHome } from "./home.js";
+export function ensureHome() {
+    for (const dir of ["workflows", "agents", "journals", "locks", "worktrees", "sessions", "loops", "receipts"]) {
+        mkdirSync(join(pstackHome(), dir), { recursive: true });
+    }
+}
+export function readJson(path, fallback) {
+    if (!existsSync(path))
+        return structuredClone(fallback);
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return structuredClone(fallback);
+    }
+}
+export function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        const fd = openSync(temp, "r+");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch { /* Preserve the original write error. */ }
+        throw error;
+    }
+    // Persist the rename on filesystems supporting directory fsync.
+    try {
+        const dirFd = openSync(dirname(path), "r");
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    catch (error) {
+        if (!["EINVAL", "ENOTSUP", "EBADF", "EPERM"].includes(error.code ?? ""))
+            throw error;
+    }
+}
+export function appendJournal(path, event) {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify({ at: new Date().toISOString(), ...event })}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export function listJson(dir) {
+    if (!existsSync(dir))
+        return [];
+    const result = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            result.push(JSON.parse(readFileSync(join(dir, name), "utf8")));
+        }
+        catch { /* corrupted records are surfaced by higher-level validation */ }
+    }
+    return result;
+}
+export function removeFile(path) {
+    rmSync(path, { force: true });
+}

package/dist/runtime/transaction.d.ts

@@ -0,0 +1,4 @@
+export declare function updateRecord<T extends {
+    id: string;
+    revision?: number;
+}>(kind: "workflow" | "agent", id: string, path: string, change: (record: T) => void, afterSave?: (record: T) => void): T;

package/dist/runtime/transaction.js

@@ -0,0 +1,44 @@
+import { FileLock } from "./lock.js";
+import { lockPath } from "./home.js";
+import { readJson, writeJsonAtomic } from "./store.js";
+// Short-lived state locks are distinct from long-lived execution/checkout locks.
+// Every read-modify-write participates in the same cross-process critical section.
+const sleepArray = new Int32Array(new SharedArrayBuffer(4));
+const DEFAULT_BUDGET_MS = 20_000;
+// One uncontended update costs about 16 ms here (read, mutate, fsync, rename), so a
+// 70-update contested burst needs about 1.1 s on an idle machine and several times
+// that under load. The default budget keeps real contention retryable; only an owner
+// that keeps renewing the lock for this long surfaces STATE_BUSY.
+function budgetMs() {
+    const raw = process.env.PSTACK_STATE_LOCK_BUDGET_MS;
+    if (raw === undefined)
+        return DEFAULT_BUDGET_MS;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 1 || value > 300_000)
+        throw new Error("PSTACK_STATE_LOCK_BUDGET_MS must be an integer between 1 and 300000");
+    return value;
+}
+export function updateRecord(kind, id, path, change, afterSave) {
+    const budget = budgetMs();
+    const lock = new FileLock(lockPath(`state-${kind}-${id}`), Math.max(15_000, budget));
+    const deadline = Date.now() + budget;
+    while (!lock.acquire()) {
+        if (Date.now() >= deadline)
+            throw new Error(`State for ${kind} ${id} is busy after ${budget} ms of contention; retry the operation.`);
+        Atomics.wait(sleepArray, 0, 0, 10);
+    }
+    try {
+        const record = readJson(path, undefined);
+        if (!record)
+            throw new Error(`Unknown ${kind}: ${id}`);
+        const previous = record.revision ?? 0;
+        change(record);
+        record.revision = previous + 1;
+        writeJsonAtomic(path, record);
+        afterSave?.(record);
+        return record;
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,202 @@
+import type { EvidencePacket } from "../agent/resources.js";
+import type { CandidateInput } from "../agent/candidates.js";
+import type { TaskBrief, TaskReport, Fingerprint, Usage, Budget, GateStatus } from "../contracts/types.js";
+export type WorkflowState = "created" | "running" | "blocked" | "paused" | "completed" | "failed" | "cancelling" | "cancelled";
+export type CallState = "pending" | "ready" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "skipped";
+export type IsolationMode = "shared" | "worktree" | "readonly";
+export type AgentProfileName = "worker" | "reviewer" | "adversary" | "repro-verifier" | "cross-judge" | "scout" | "architect" | "verifier" | "synthesizer" | "integrator" | "poteto-agent" | "comment-sicko";
+export interface DurableError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    cause?: string;
+    occurredAt: string;
+}
+export interface AgentRecord {
+    evidencePackets?: EvidencePacket[];
+    candidateInputs?: CandidateInput[];
+    brief?: TaskBrief;
+    baseline?: Fingerprint;
+    report?: TaskReport;
+    reportError?: string;
+    usage?: Usage;
+    thinkingLevel?: ThinkingLevelName;
+    budget?: Budget;
+    id: string;
+    revision?: number;
+    parentSessionId?: string;
+    workflowId?: string;
+    callKey?: string;
+    profile: AgentProfileName | string;
+    task: string;
+    state: "created" | "running" | "completed" | "failed" | "cancelling" | "cancelled";
+    model?: string;
+    modelSelection?: {
+        requested: string;
+        effective: string;
+        notes: string[];
+    };
+    cwd: string;
+    isolation: IsolationMode;
+    worktree?: string;
+    branch?: string;
+    worktreeRepoRoot?: string;
+    worktreeBaseRef?: string;
+    sessionFile?: string;
+    sessionDir?: string;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    result?: string;
+    error?: DurableError;
+    attempt: number;
+    depth: number;
+}
+export interface WorkflowCall {
+    /** A failed candidate excluded before a comparison, never an accepted artifact. */
+    excludedFromSelection?: boolean;
+    evidencePackets?: EvidencePacket[];
+    brief?: TaskBrief;
+    thinkingLevel?: ThinkingLevelName;
+    budget?: Budget;
+    verification?: {
+        status: GateStatus;
+        ledgerId?: string;
+        reason?: string;
+    };
+    artifactId?: string;
+    report?: TaskReport;
+    reportError?: string;
+    usage?: Usage;
+    key: string;
+    profile: AgentProfileName | string;
+    task: string;
+    state: CallState;
+    dependsOn: string[];
+    attempt: number;
+    model?: string;
+    modelSelection?: {
+        requested: string;
+        effective: string;
+        notes: string[];
+    };
+    isolation?: IsolationMode;
+    cwd?: string;
+    agentId?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    result?: string;
+    error?: DurableError;
+}
+export interface WorkflowEdge {
+    from: string;
+    to: string;
+}
+export interface WorkflowRecord {
+    completionPolicy?: 'first-pass';
+    firstPassWinner?: string;
+    modelNotes?: string[];
+    deliveryContract?: "local-dag" | "candidate-only" | "remote-stack-required";
+    schemaVersion?: 2;
+    reviewFingerprint?: Fingerprint;
+    budget?: Budget;
+    verification?: "unknown" | "verified" | "blocked" | "stale";
+    id: string;
+    revision?: number;
+    name?: string;
+    type: "single" | "parallel" | "chain" | "graph" | "swarm" | "arena" | "orchestrate" | "review" | "loop";
+    state: WorkflowState;
+    createdAt: string;
+    updatedAt: string;
+    parentSessionId?: string;
+    parentCwd: string;
+    calls: Record<string, WorkflowCall>;
+    edges: WorkflowEdge[];
+    maxConcurrency: number;
+    result?: string;
+    error?: DurableError;
+    cancelledAt?: string;
+    upstreamContext?: {
+        pstackVersion: string;
+        skill?: string;
+        playbook?: string;
+    };
+}
+export interface DispatchRecord {
+    id: string;
+    owner: string;
+    programId: string;
+    unitKey: string;
+    workflowId: string;
+    briefDigest: string;
+    ordersRevision?: number;
+    state: "committed" | "materialized";
+    workflow: WorkflowRecord;
+    createdAt: string;
+    materializedAt?: string;
+}
+export interface LoopRecord {
+    id: string;
+    sessionId: string;
+    intervalMs: number;
+    task: string;
+    enabled: boolean;
+    createdAt: string;
+    nextRunAt: string;
+    lastRunAt?: string;
+    missedPolicy: "run-once" | "skip";
+}
+export interface RuntimeConfig {
+    version: 1;
+    skillsEnabled: boolean;
+    defaultConcurrency: number;
+    loopMissedPolicy: "run-once" | "skip";
+}
+export type ThinkingLevelName = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface ModelConfig {
+    panels?: Record<string, string[]>;
+    workflows?: Record<string, Record<string, string>>;
+    version: 1;
+    roles: Record<string, string>;
+    thinkingLevel: "inherit-parent" | ThinkingLevelName;
+    fallbackPolicy?: "disabled" | "same-family";
+}
+export interface AgentProfile {
+    name: AgentProfileName | string;
+    description: string;
+    tools: string[];
+    writable: boolean;
+    defaultIsolation: IsolationMode;
+    defaultRole: string;
+    systemPrompt: string;
+}
+export interface WorkflowNodeSpec {
+    evidencePackets?: EvidencePacket[];
+    brief?: TaskBrief;
+    thinkingLevel?: ThinkingLevelName;
+    budget?: Budget;
+    key: string;
+    profile?: AgentProfileName | string;
+    task: string;
+    dependsOn?: string[];
+    model?: string;
+    /** Named task role, distinct from the tool-permission profile. */
+    modelRole?: string;
+    isolation?: IsolationMode;
+}
+export interface WorkflowRunSpec {
+    completionPolicy?: 'first-pass';
+    modelNotes?: string[];
+    deliveryContract?: "local-dag" | "candidate-only" | "remote-stack-required";
+    contractLevel?: "strict" | "minimal";
+    budget?: Budget;
+    name?: string;
+    type?: WorkflowRecord["type"];
+    nodes: WorkflowNodeSpec[];
+    maxConcurrency?: number;
+    parentSessionId?: string;
+    cwd: string;
+    pstackVersion?: string;
+    skill?: string;
+    playbook?: string;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/upstream.d.ts

@@ -0,0 +1,2 @@
+/** The active source pin; semantic approval is recorded separately from source availability. */
+export declare function upstreamVersion(): string;

package/dist/runtime/upstream.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+/** The active source pin; semantic approval is recorded separately from source availability. */
+export function upstreamVersion() {
+    const metadata = JSON.parse(readFileSync(new URL('../../UPSTREAM.json', import.meta.url), 'utf8'));
+    if (typeof metadata.version !== 'string' || !/^[\w.+-]+$/.test(metadata.version))
+        throw new Error('UPSTREAM_METADATA_INVALID');
+    return metadata.version;
+}

package/dist/setup/command.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare function runSetup(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void>;