specpi 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.18.0 - 2026-09-07
+
+- Start Command Guard off in RPC sessions, including new SpecPi Chat conversations. Explicit `/guard guard` and `/guard strict` still enable protection for the current session; the terminal startup chooser is unchanged.
+
+- Let installer PATH discovery continue past inaccessible candidates while preserving permission errors for explicit executable paths. Use the pinned repository Pi for test fixtures and a temporary npm cache for package validation, so restricted test accounts do not require personal npm access.
+
+- Publish bounded delegate lifecycle metadata through Pi's RPC widget protocol for SpecPi Chat's live panel. Add exact-attempt human cancellation, stop sampling on settlement/shutdown, and keep prior-generation task labels out of replacement sessions. Worker policy, model-facing operations, quotas and provider behavior are unchanged.
+
 ## 0.17.1 - 2026-09-07
 
 - Reduce the npm package by shipping only runtime scripts; remove obsolete plans, research documents and unused assets, and shorten operational guides.

package/README.md

@@ -48,7 +48,7 @@ specpi doctor
 
 Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
 
-To pin this release, use `npm install --global specpi@0.17.1`.
+To pin this release, use `npm install --global specpi@0.18.0`.
 
 Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
@@ -62,7 +62,7 @@ Chat beside your code, attach files, and switch conversations.
 
 In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
 
-Chat 0.3.7 includes **Restart Pi** in the Chat title bar and Command Palette to reconnect the selected conversation and reload its Pi extensions. Other conversations keep running.
+Chat 0.4.0 adds live delegate progress and worker Stop controls, plus compact tags for attached files. With SpecPi 0.18.0, new Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it. Update the harness and use **Restart Pi** to load these changes.
 
 ## Go further
 

package/SECURITY_MODEL.md

@@ -95,6 +95,8 @@ SpecPi is not an operating-system sandbox and does not claim to contain a compro
 
 ## Installer and managed state
 
+Installer executable discovery skips inaccessible candidates in an implicit PATH search; it neither changes their permissions nor executes them. Explicit executable paths and unexpected filesystem errors still fail. The existing Windows winget App Execution Alias handling is unchanged.
+
 SpecPi is configuration and executable extension code for Pi and runs with the invoking user's permissions. Installing the public npm package adds the `specpi` CLI to npm-managed state but does not run SpecPi installation, download external tools, or mutate Pi state; the package defines no npm install lifecycle script. The installer prints a plan and requires confirmation unless `--yes` is supplied. `plan` is non-mutating. Installation and update merge documented settings leaves, preserve unrelated packages and configuration, and modify AGENTS and shell files only inside SpecPi marker blocks.
 
 The canonical npm route is an installer-CLI distribution. Direct `pi install npm:specpi` loads packaged extensions, skills, and themes but bypasses the managed installer, so it does not provide managed instructions, supporting packages, browser runtime acquisition, optional tools, shell integration, backups, or ownership records. Pi-bundled runtime modules are optional peers and are not copied into the tarball. Release automation validates the packed artifact, requires a matching immutable version and release tag, publishes only from a protected environment, and requests npm provenance through short-lived GitHub OIDC credentials.
@@ -189,7 +191,7 @@ Repository checks, smoke tests, checksums, closed capability validators, and bro
 
 The optional `vscode/` extension is distributed separately from the SpecPi npm installation. It runs in the VS Code workspace extension host and requires a trusted filesystem workspace before launching Pi or collecting file context. Only application-level settings choose executable paths; the launcher resolves native executables or known adjacent Pi JavaScript entry points and never executes a shell command string. Pi runs in the explicitly selected workspace with its normal installed extensions and provider configuration. VS Code trust does not replace Pi project trust, and the extension does not pass a flag to bypass Pi's trust decisions or Command Guard.
 
-The sidebar uses Pi's documented JSONL RPC protocol. Pi owns provider authentication and tool execution; the extension does not read, copy, or manage authentication files. RPC model metadata is projected to display fields. Approvals and selection/input/editor requests are displayed as text and require an exact response for the requesting conversation's active request. Switching the displayed conversation preserves outstanding requests; background requests appear as needing input and never receive automatic approval. Stop, disconnect, runtime session transitions, and expiry cancel the affected conversation's requests. Expired or wrong-conversation responses cannot authorize later requests. In RPC, Command Guard starts in Guard mode without an initial selection dialog because Pi cannot read dialog responses until its startup handlers return; explicit `/guard` commands remain available after startup. Unsupported terminal-only components are disclosed rather than treated as functional editor controls.
+The sidebar uses Pi's documented JSONL RPC protocol. Pi owns provider authentication and tool execution; the extension does not read, copy, or manage authentication files. RPC model metadata is projected to display fields. Approvals and selection/input/editor requests are displayed as text and require an exact response for the requesting conversation's active request. Switching the displayed conversation preserves outstanding requests; background requests appear as needing input and never receive automatic approval. Stop, disconnect, runtime session transitions, and expiry cancel the affected conversation's requests. Expired or wrong-conversation responses cannot authorize later requests. In RPC, including SpecPi Chat, Command Guard starts off without an initial selection dialog because Pi cannot read dialog responses until its startup handlers return. Explicit `/guard guard` and `/guard strict` commands enable protection for the current session; new sessions start off again. The terminal startup chooser and initialization-failure handling are unchanged. Unsupported terminal-only components are disclosed rather than treated as functional editor controls.
 
 Chat allows up to 90 seconds for an initial read-only RPC readiness probe before sending normal requests. This accommodates the 30-second startup fallback in older installed Guard versions without extending later request deadlines. Dialogs arriving before readiness receive cancellation only, never an approval or mode selection; the sidebar explains the limitation and retains a notice after connection. An extension with an unbounded startup dialog can still prevent readiness. Chat times out with recovery guidance instead of bypassing that extension or changing the user's installed harness.
 
@@ -207,6 +209,8 @@ Pi persists chats, including sent image blocks, in a workspace-specific director
 
 Conversation edits select entries from the active Pi tree, revalidate the selection before mutation, and fork before the chosen user prompt. Exact original text and validated image blocks are captured before forking because Pi's fork response returns text only. The original conversation is retained, restored drafts require another send action, and conversation forks/clones do not restore or checkpoint workspace files. Actions are scoped to the active workspace, connection, and session revision. Export opens an unsaved Markdown document and Copy Conversation writes the visible Markdown to the OS clipboard only on explicit request. Both omit image bytes and represent images as placeholders; they do not reconstruct truncated or hidden history. Usage displays report Pi measurements, preserving unavailable values rather than inventing totals. The separate provider Limits row projects bounded strings from the known Codex Usage and pi-usage status keys, strips terminal/control sequences, and inserts text only. It does not parse numeric quotas, combine budgets with conversation cost, read provider credentials or usage-cache files, or add provider requests. Reports stay with their live connection and are cleared on disconnect, exit, and reconnect; refreshing and cache age remain upstream plugin responsibilities. Opening the details has no RPC or provider side effect. Existing `/usage` notifications and exact confirmation dialogs continue through the normal UI protocol; no automatic reset consumption or terminal-footer emulation is added.
 
+The Delegates panel consumes the known `specpi-delegation-v1` RPC widget key, with one versioned JSON record of at most 32 KiB and eight projected worker rows. Public identities, shortened task labels, states, elapsed times, call counts and code-owned diagnostics are text-only; snapshots, full prompts, raw provider errors and child transcripts are not sent through the live widget. A single extension-side timer samples existing counters while slots are occupied; it makes no provider or source requests and is disposed on shutdown/rebinding. Invalidated-generation jobs contribute only to occupied-slot counts, not cross-session task labels; replaced same-generation stopping jobs remain visible until settlement. Chat clears live state on disconnect, exit and runtime session replacement and keeps at most 32 connection-local completion summaries for refresh; it adds no child journal or webview persistence. Existing delegate tool receipts are projected into readable advisory reports without changing their model/session content. Stop actions require a trusted workspace, foreground conversation, matching context and an observed running/queued batch/job/attempt. Pi rechecks that exact attempt before its human command cancels it. Worker Stop does not submit draft text/images, clear parent queues, approve tools, change quotas or claim remote termination. The widget is an integration contract with trusted installed extensions, not protection against a malicious extension in Pi's process.
+
 Native change review reads VS Code's Git API, validates selected workspace paths, and opens the corresponding working-tree or staged view through the built-in diff/editor actions. It does not execute a shell command, stage, commit, discard, or restore files. Git integration availability and the filesystem race boundary still apply. The sidebar coordinator keeps independent Pi connections for explicitly opened conversations. Switching conversations or folders only changes the selected view. Stop and Disconnect target the selected process; extension-host shutdown stops all owned processes. User-initiated parallel conversations share their workspace files and are not isolated worktrees. Branching uses Pi's pre-runtime `--fork` to copy into a new owned session before extensions can write, then performs any active-branch or prompt selection there; the original process and session remain unchanged.
 
 The extension introduces no network server, telemetry, runtime package dependency, or automatic model request when a view opens. Pi itself may contact its configured services when connected. Tests use synthetic homes, agent directories, providers, workspaces and profiles, plus an installed VS Code extension host; they do not access the user's live Pi credentials or conversations. Live provider availability and billing are outside the offline test evidence.

package/docs/delegation/README.md

@@ -16,7 +16,7 @@ The parent remains the sole writer and verifies workers' evidence. Use delegatio
 
 Startup enables dispatch only after host, settings and Guard checks; it launches no workers. Preflight may perform Pi-owned authentication/OAuth preparation. Off and safety revocations survive reload/session switches; restarting Pi restores the on default. While off, the tool is absent from model requests.
 
-The TUI panel shows worker state, elapsed time and call counts. **Ready for review** requires a parent disposition; **stopping** still occupies a slot. RPC/print modes return structured results without widgets. Expand tool output for findings and evidence.
+The TUI panel shows worker state, elapsed time and call counts. **Ready for review** requires a parent disposition; **stopping** still occupies a slot. RPC mode additionally publishes bounded, versioned worker metadata for SpecPi Chat's live Delegates panel; print/JSON modes do not mount widgets. Chat shows expandable tasks/metrics, attempt-bound Stop controls, and advisory transcript summaries. Update both Chat and the harness, then restart Pi. Expand tool output for findings and evidence.
 
 Model/thinking changes revoke old results and preflight the new route. Unsupported routes pause dispatch; compatible selections resume it unless explicitly off. Guard, session, branch and task/scope changes revoke the current generation. Ordinary conversation advancement does not. Reload/off/on never reset spent process quotas or release unsettled requests. Restart Pi to load changed runtime code or a different working root.
 

package/docs/delegation/protocol.md

@@ -240,6 +240,29 @@ cache. After eviction, those operations are revalidated against current state; t
 cannot start inference or restore cancelled jobs. Generation and source checks still
 apply. Neither cache eviction nor failed attempts reset quotas or block cancellation.
 
+## RPC display metadata
+
+In RPC mode, the extension emits `setWidget` with key `specpi-delegation-v1`
+and a single JSON string in `widgetLines`. Version 1 contains `enabled`, occupied
+`active` slots, `concurrency`, process `calls`/`callLimit`, and at most eight job rows.
+Rows contain batch/job/attempt IDs, mode, state, settlement, call/tool counters,
+elapsed milliseconds, a shortened task label, public provider/model names,
+parent disposition and code-owned diagnostics. No source snapshots, full prompts,
+child transcript or provider query is part of this channel. Sampling is at most
+once a second between lifecycle updates and stops when no slots are occupied.
+Invalidated-generation job identities/tasks are omitted; their unsettled slots still
+count. A replaced batch in the same generation remains visible until settlement.
+Shutdown/rebinding clears the old widget and timer. No new persistent store is added.
+
+Chat treats this payload as untrusted, accepts one bounded versioned record, strips
+controls and renders text only. Its Stop button invokes
+`/delegate cancel-worker <batchId> <jobId> <attemptId>` through normal RPC command
+dispatch. This human UI command checks the exact current queued/running attempt
+before cancellation; it cannot cancel a later follow-up under the same job name,
+start inference, raise limits or alter the user's draft/attachments. Parent Stop and
+worker Stop are separate controls. Neither stopping nor settlement proves remote
+termination. Existing model-facing `cancel` requests are unchanged.
+
 ## Cancellation and lifecycle
 
 ```json

package/extensions/command-guard/index.ts

@@ -163,7 +163,7 @@ export default function registerCommandGuard(
         approvalTimeoutMs?: number;
     } = {},
 ): void {
-    // Startup only picks a default and falls back to the recommended Guard mode, so it stays short.
+    // The terminal startup chooser falls back to Guard, so it stays short; RPC starts off without a dialog.
     // An approval waits on a person reading severity, category, cwd, affected paths, reason, and alternative;
     // withTimeout cannot cancel the underlying prompt, so a short bound would deny work mid-decision and leave
     // a live selector on screen. Both directions still fail closed, just on a human timescale.
@@ -230,14 +230,14 @@ export default function registerCommandGuard(
         try {
             subscribeGuardState();
             // Pi RPC binds session_start before it starts reading UI responses.
-            // Begin guarded without a startup dialog; /guard remains available
+            // Begin off without a startup dialog; /guard remains available
             // for explicit changes once the RPC client is connected.
             const choice = ctx.hasUI && ctx.mode !== "rpc" ? await startupChoice(ctx, startupTimeoutMs) : undefined;
             if (state.generation !== startupGeneration) {
                 return;
             }
 
-            let mode: "guard" | "strict" | "off" = "guard";
+            let mode: "guard" | "strict" | "off" = ctx.mode === "rpc" ? "off" : "guard";
             if (choice === "Strict") {
                 mode = "strict";
             } else if (choice === "Off for this session") {

package/extensions/delegation/core.mjs

@@ -86,8 +86,9 @@ export function createDelegationController({
         cost: "unavailable; no invoice cap",
         batches: [...[...history.values()].map((item) => structuredClone(item)), ...[...batches.values()].map(summary)],
     });
-    // Presentation reads counters only: no source checks, provider queries or retained worker text.
-    const presentation = () => ({
+    // Presentation samples bounded metadata only: no source checks or provider queries.
+    // RPC includes terminal rows so a stopped worker does not silently disappear.
+    const presentation = ({ includeInactive = false } = {}) => ({
         enabled,
         active,
         concurrency: policy.concurrency,
@@ -95,9 +96,24 @@ export function createDelegationController({
         callLimit: policy.sessionCalls,
         jobs: [...batches.values()].flatMap((batch) =>
             [...batch.jobs.values()]
-                .filter((job) => job.settling || (!batch.retired && !quiet.has(job.state) && !job.disposition))
+                .filter((job) =>
+                    includeInactive
+                        ? batch.generation === generation
+                        : job.settling || (!batch.retired && !quiet.has(job.state) && !job.disposition),
+                )
                 .map((job) => ({
                     id: job.spec.id,
+                    ...(includeInactive
+                        ? {
+                              batchId: batch.id,
+                              attemptId: job.attemptId,
+                              task: job.spec.question?.slice(0, 240) || "",
+                              provider: batch.model?.provider,
+                              model: batch.model?.id,
+                              disposition: job.disposition?.decision ?? null,
+                              error: job.error ?? null,
+                          }
+                        : {}),
                     mode: job.mode,
                     state: job.state,
                     settling: job.settling,
@@ -395,6 +411,13 @@ export function createDelegationController({
                         }
 
                         active -= 1;
+                        // A replaced batch can still own a stopping worker. Publish
+                        // its settlement before cleanup removes it, but never expose
+                        // an invalidated generation to the new context.
+                        if (batch.retired && batch.generation === generation) {
+                            changed();
+                        }
+
                         cleanupBatch(batch);
                         changed();
                         pump();

package/extensions/delegation/extension.mjs

@@ -2,7 +2,13 @@ import { DelegationError, publicErrorMessage } from "./errors.mjs";
 import { randomUUID } from "node:crypto";
 import { createDelegationController } from "./core.mjs";
 import { DEFAULT_TIMEOUT_MINUTES, DEFAULT_BUDGET_MULTIPLIER, timeoutLimits, budgetLimits } from "./protocol.mjs";
-import { createLivePanel, createToolRenderers, readableLimits, readableStatus } from "./presentation.mjs";
+import {
+    createLivePanel,
+    createRpcPanel,
+    createToolRenderers,
+    readableLimits,
+    readableStatus,
+} from "./presentation.mjs";
 
 const USAGE =
     "Usage: /delegate [on|off|status|limits|budget [<multiplier>|reset]|timeout [<minutes>|reset]|cancel <batchId>]";
@@ -154,6 +160,7 @@ export function createDelegationExtension(
     };
 
     const panel = presentation ? createLivePanel(() => controller.presentation(), presentation) : undefined;
+    const rpcPanel = createRpcPanel(() => controller.presentation({ includeInactive: true }));
 
     const status = () => ({
         ...controller.status(),
@@ -176,6 +183,7 @@ export function createDelegationExtension(
                   : undefined,
         );
         panel?.update();
+        rpcPanel.update();
     }
 
     function invalidate(reason, preserveStartupDefault = false) {
@@ -207,6 +215,7 @@ export function createDelegationExtension(
 
     const factory = (pi) => {
         panel?.dispose();
+        rpcPanel.dispose();
         detach();
         bindingEpoch += 1;
         const issuedEpoch = bindingEpoch;
@@ -360,6 +369,7 @@ export function createDelegationExtension(
             currentContext = ctx;
             toolsReady = true;
             panel?.bind(ctx);
+            rpcPanel.bind(ctx);
             invalidate("session started or resources reloaded", true);
             try {
                 loadTimeout();
@@ -390,6 +400,7 @@ export function createDelegationExtension(
 
             invalidate("session shutdown");
             panel?.dispose();
+            rpcPanel.dispose();
             prepareContext(undefined, true);
             detach();
             currentContext = undefined;
@@ -443,9 +454,49 @@ export function createDelegationExtension(
                 }
 
                 currentContext = ctx;
-                const [action = "status", id, extra] = args.trim().split(/\s+/u).filter(Boolean);
+                const [action = "status", id, extra, attemptId, ...rest] = args.trim().split(/\s+/u).filter(Boolean);
                 try {
-                    if (extra || (id && !["cancel", "timeout", "budget"].includes(action))) {
+                    // Chat binds Stop to an exact observed attempt, never a future
+                    // follow-up with the same job name. This command starts no model turn.
+                    if (action === "cancel-worker") {
+                        const job = controller
+                            .presentation({ includeInactive: true })
+                            .jobs.find(
+                                (candidate) =>
+                                    candidate.batchId === id &&
+                                    candidate.id === extra &&
+                                    candidate.attemptId === attemptId,
+                            );
+                        if (!ctx.hasUI || rest.length || !job || !["queued", "running"].includes(job.state)) {
+                            ctx.ui.notify(
+                                "That delegate attempt is no longer running. Its state was not changed.",
+                                "warning",
+                            );
+                            updatePresentation();
+
+                            return;
+                        }
+
+                        await controller.execute({
+                            operation: "cancel",
+                            requestId: `human-${randomUUID()}`,
+                            batchId: id,
+                            jobId: extra,
+                        });
+                        ctx.ui.notify(
+                            "Delegate stop requested. The slot stays occupied until Pi reports settlement; remote termination is not guaranteed.",
+                            "info",
+                        );
+
+                        return;
+                    }
+
+                    if (
+                        extra ||
+                        attemptId ||
+                        rest.length ||
+                        (id && !["cancel", "timeout", "budget"].includes(action))
+                    ) {
                         throw new DelegationError(USAGE);
                     }
 

package/extensions/delegation/presentation.mjs

@@ -139,6 +139,88 @@ export function createLivePanel(getView, { truncateToWidth }) {
     };
 }
 
+// Versioned display metadata over Pi's supported string-array widget transport.
+// Never send snapshots, full prompts, child transcripts or raw provider diagnostics.
+export function createRpcPanel(getView) {
+    const key = "specpi-delegation-v1";
+    let context;
+    let timer;
+    let signature;
+    const dispose = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        if (context?.mode === "rpc") {
+            try {
+                context.ui.setWidget(key, undefined);
+            } catch {
+                // UI teardown cannot affect worker ownership.
+            }
+        }
+
+        context = undefined;
+        signature = undefined;
+    };
+
+    const update = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        if (context?.mode !== "rpc" || !context.ui?.setWidget) {
+            return;
+        }
+
+        const view = getView();
+        const payload = {
+            version: 1,
+            enabled: view.enabled,
+            active: view.active,
+            concurrency: view.concurrency,
+            calls: view.calls,
+            callLimit: view.callLimit,
+            jobs: view.jobs.slice(0, 8).map((job) => ({
+                id: job.id,
+                batchId: job.batchId,
+                attemptId: job.attemptId,
+                mode: job.mode,
+                state: job.state,
+                settling: job.settling,
+                calls: job.calls,
+                tools: job.tools,
+                elapsedMs: job.elapsedMs,
+                disposition: job.disposition,
+                task: plain(job.task).slice(0, 240),
+                provider: plain(job.provider).slice(0, 128),
+                model: plain(job.model).slice(0, 128),
+                error: job.error ? plain(job.error).slice(0, 512) : null,
+            })),
+        };
+        const next = JSON.stringify(payload);
+        if (next !== signature) {
+            context.ui.setWidget(key, [next]);
+            signature = next;
+        }
+
+        if (view.active > 0) {
+            timer = setTimeout(() => {
+                try {
+                    update();
+                } catch {
+                    // Optional RPC UI failures never escape the sampling timer.
+                }
+            }, 1000);
+            timer.unref?.();
+        }
+    };
+
+    return {
+        update,
+        dispose,
+        bind(ctx) {
+            dispose();
+            context = ctx;
+        },
+    };
+}
+
 export function readableStatus(state) {
     const mode = state.enabled ? "enabled" : state.updating ? "updating model" : state.requested ? "paused" : "off";
     const lines = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "An explicit, privacy-conscious, self-improving harness for the Pi coding agent",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/specpi.mjs

@@ -172,6 +172,12 @@ function resolveCommand(command, env = process.env) {
                     return path.resolve(file);
                 }
 
+                // Like shell PATH lookup, continue past inaccessible candidates.
+                // Explicit executable paths must still report permission failures.
+                if (!hasPath && (error.code === "EACCES" || error.code === "EPERM")) {
+                    continue;
+                }
+
                 if (error.code !== "ENOENT" && error.code !== "ENOTDIR") {
                     throw error;
                 }