specpi 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.20.1 - 2026-09-10
+
+- Enable `structural_search` by default on fresh installs and updates without a saved choice. Persist enablement transactionally and preserve explicit opt-outs; disable with `specpi update --structural-search=off`, then restart Pi.
+- Keep acquisition skip flags, malformed-configuration failures, selected-source limits and Command Guard approvals unchanged. Unsupported native hosts must pass `--structural-search=off` during install/update to avoid runtime acquisition failures.
+
 ## 0.20.0 - 2026-09-09
 
 - Add opt-in `structural_search` with pinned ast-grep 0.45.3, protected explicit source selection, bounded output and subprocess cleanup, and exact-call approval in Strict mode. Enable with `specpi update --structural-search=on`, then restart Pi.

package/README.md

@@ -32,7 +32,7 @@ SpecPi extends Pi with chat, review tools, and focused delegation. Its principle
 - **Focused delegation.** One agent makes changes. Up to two read-only subagents help investigate and review. [Research and design](https://tannermidd.github.io/SpecPi/single-agent/)
 - **Background tasks.** Start an approved dev server, test suite, or watch build, inspect bounded output, and stop it without blocking other work.
 - **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
-- **Structural search.** Opt into bounded ast-grep patterns over selected code with `specpi update --structural-search=on`. [Usage and limits](docs/structural-search.md)
+- **Structural search.** Bounded ast-grep patterns over selected code are enabled by default. Disable with `specpi update --structural-search=off`; on unsupported native hosts, pass `--structural-search=off` during installation too. [Usage and limits](docs/structural-search.md)
 - **Accessibility checks.** Scan the current browser state for automated WCAG and optional best-practice findings. [Browser verification](docs/browser-testing.md)
 - **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
 
@@ -51,7 +51,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.20.0`.
+To pin this release, use `npm install --global specpi@0.20.1`.
 
 Delegation is enabled at startup. Use `/delegate off` to turn it off.
 

package/SECURITY_MODEL.md

@@ -197,7 +197,7 @@ The browser is not an operating-system or network sandbox. Use a container or VM
 
 ## Structural search
 
-Structural search is disabled until explicitly selected. The owned `specpi/tool-integrations.json` file stores nonsecret enablement; plan does not mutate it, updates back it up and roll it back with managed state, and uninstall preserves it. Unparseable content does not abort the non-mutating plan and does not silently enable anything: install and update stop and name the file unless an explicit `--structural-search` selection rewrites it, and the prior bytes go to the operation backup first. A configuration that is a link or not a bounded regular file stays a hard failure that no selection rewrites. The extension itself treats any unreadable configuration as disabled. Runtime acquisition is private, pinned, script-free and transactional. Configuration output is checked against the same 16 KiB bound as reads before mutation, with compact JSON fallback. Doctor checks source/runtime integrity before its offline fixture; unverified or modified prior runtime directories are preserved rather than deleted. Runtime ownership now binds the acquired tree's contents, paths, directories, permissions and link targets; the tree fingerprint does not traverse links, and the marker is checked separately. Legacy binary-only markers remain unverified. Retirement rechecks the tree before deletion. Rollback quarantines the new runtime and restores the prior directory before attempting recursive cleanup, reporting any retained quarantine. No global executable search or PATH injection is used.
+Structural search is enabled by default when no enablement configuration exists; an explicit saved opt-out remains disabled on update or reinstall. The owned `specpi/tool-integrations.json` file stores nonsecret enablement; plan does not mutate it, updates back it up and roll it back with managed state, and uninstall preserves it. Unparseable content does not abort the non-mutating plan and does not silently enable anything: install and update stop and name the file unless an explicit `--structural-search` selection rewrites it, and the prior bytes go to the operation backup first. A configuration that is a link or not a bounded regular file stays a hard failure that no selection rewrites. The extension itself treats any unreadable configuration as disabled. Runtime acquisition is private, pinned, script-free and transactional. Enabled acquisition or smoke failures abort install/update and roll back managed changes; unsupported native hosts must explicitly opt out with `--structural-search=off` or skip acquisition. Configuration output is checked against the same 16 KiB bound as reads before mutation, with compact JSON fallback. Doctor checks source/runtime integrity before its offline fixture; unverified or modified prior runtime directories are preserved rather than deleted. Runtime ownership now binds the acquired tree's contents, paths, directories, permissions and link targets; the tree fingerprint does not traverse links, and the marker is checked separately. Legacy binary-only markers remain unverified. Retirement rechecks the tree before deletion. Rollback quarantines the new runtime and restores the prior directory before attempting recursive cleanup, reporting any retained quarantine. No global executable search or PATH injection is used.
 
 The parent captures explicit selected source with the existing snapshot path/private-store/link/descriptor/digest checks. A parent-only byte callback rechecks the original digest and clears its buffer after parsing. Existing workers gain no tool or byte API route. Files are capped at 1 MiB, selection at 8 MiB/200 files, pattern at 4 KiB, returned evidence at 24 KiB, raw stdout at 2 MiB and stderr at 8 KiB per call. Source bytes go to a reviewed native parser over stdin; only a neutral configuration is written to private scratch. Files containing secrets under ordinary source names are not automatically detectable.
 

package/docs/structural-search.md

@@ -1,15 +1,15 @@
 # Structural search
 
-`structural_search` is an opt-in, read-only ast-grep 0.45.3 tool. It matches code structures across formatting changes. It does not resolve types/references, edit code or replace literal search for comments, strings and filenames.
+`structural_search` is a default-on, read-only ast-grep 0.45.3 tool. It matches code structures across formatting changes. It does not resolve types/references, edit code or replace literal search for comments, strings and filenames.
 
-Enable it through the installer, then restart Pi:
+Provision it through the installer, then restart Pi:
 
 ```sh
-specpi plan --structural-search=on
-specpi update --structural-search=on
+specpi plan
+specpi update
 ```
 
-For a fresh installation use `install`. `--yes` confirms installation but does not opt into structural search by itself. Omission preserves the existing choice. `--skip-package-install` and `--skip-tool-install` skip acquisition without disabling an existing runtime. Direct `pi install npm:specpi` does not provision the runtime; use the SpecPi installer for setup.
+For a fresh installation use `install`. With no saved choice, structural search is enabled by default on install and update. Omitting `--structural-search` preserves a saved choice, including an explicit opt-out. Use `--structural-search=on` to re-enable it. `--yes` confirms the operation without changing that selection. `--skip-package-install` and `--skip-tool-install` skip acquisition without disabling an existing runtime. Direct `pi install npm:specpi` does not provision the runtime; use the SpecPi installer for setup.
 
 ```json
 {
@@ -31,10 +31,10 @@ The parser receives selected source over stdin, a fixed argument list, a neutral
 
 Guard and Off permit these bounded reads; Strict asks for the exact call. The approval receives the operation cancellation signal and remaining timeout. Terminal prompts dismiss on cancellation; Pi 0.84.4 releases cancelled RPC approvals server-side but sends no remote dismissal event, so clients may display them until the forwarded timeout expires. Late answers cannot authorize the cancelled call. Locked or ambiguous Guard state denies. If Guard is absent, the same source/input limits remain. Policy, root and enablement are rechecked before parsing. A denial must not be retried through a different tool. Existing read-only workers do not gain structural-search access.
 
-Enablement lives in `<agentDir>/specpi/tool-integrations.json`. The installer preserves unrelated fields, backs up the owned file before changes and rolls it back on failure. Serialized configuration must also fit the 16 KiB reader limit: the installer uses compact JSON when needed and rejects output that still exceeds the limit before changing configuration or runtimes. If that file becomes unparseable, `plan` reports it and continues without mutating anything, while `install` and `update` stop and name the file; repair or remove it, or pass `--structural-search=on` or `--structural-search=off` to rewrite it from the backed-up original. A configuration that is a link or not a bounded regular file remains a hard failure that no selection rewrites. The private runtime has an exact npm lockfile, script-free acquisition and binary/full-tree checksums; no global PATH entry is added. Doctor checks integrity and runs an offline fixture smoke. The initial native platforms are Windows x64, macOS x64/arm64 and Linux glibc x64; other combinations report unavailable.
+Enablement lives in `<agentDir>/specpi/tool-integrations.json`. The installer preserves unrelated fields, backs up the owned file before changes and rolls it back on failure. Serialized configuration must also fit the 16 KiB reader limit: the installer uses compact JSON when needed and rejects output that still exceeds the limit before changing configuration or runtimes. If that file becomes unparseable, `plan` reports it and continues without mutating anything, while `install` and `update` stop and name the file; repair or remove it, or pass `--structural-search=on` or `--structural-search=off` to rewrite it from the backed-up original. A configuration that is a link or not a bounded regular file remains a hard failure that no selection rewrites. The private runtime has an exact npm lockfile, script-free acquisition and binary/full-tree checksums; no global PATH entry is added. Doctor checks integrity and runs an offline fixture smoke. The supported native platforms are Windows x64, macOS x64/arm64 and Linux glibc x64. On other hosts, use `specpi install --structural-search=off` (or `update`) to avoid acquiring an unsupported runtime. With structural search enabled, acquisition or smoke failures abort install/update and roll back managed changes rather than silently disabling the tool; tool calls on unsupported hosts report unavailable.
 
 Disable with `specpi update --structural-search=off`, then restart Pi. Intact owned runtimes are removed transactionally. Modified/unverified runtimes are preserved with a warning; replacement preserves them outside the active runtime path. The tree check covers file contents, paths, directories, permissions and link targets without traversing links, and is repeated before retired-tree deletion. Older ownership markers without a tree checksum are unverified and preserved. Rollback quarantines the new runtime and restores the prior directory before recursive cleanup; a cleanup failure reports the retained quarantine path. Uninstall preserves enablement configuration and user evidence. Trusted native executables still run with the user's permissions; these controls are not an OS sandbox.
 
 Development verification uses `npm run setup:structural` followed by `npm run test:structural`. This installs only the locked native test runtime in `.specpi-test/structural-runtime/`. Installer tests use disposable Pi directories and skip external acquisition.
 
-Six synthetic lookup trials on Windows x64 / Node 24.18.0 on September 9, 2026 covered call sites, constructors, filesystem calls, JSX/TSX components and Python calls. Each fixture contained two valid structures with different formatting plus one comment/string decoy. All 12 expected matches were found with no false positives; each response was 669–707 bytes and took 32–48 ms in that single run. A simple fixed-string `rg` query per fixture found six valid matches, missed six formatting variants and returned six decoys (37–85 bytes, 24–33 ms per query). This demonstrates the intended syntax-sensitive use case, not superiority over carefully constructed regex/manual inspection or measured agent productivity. Literal search remains faster and smaller in these trials; structural search remains opt-in.
+Six synthetic lookup trials on Windows x64 / Node 24.18.0 on September 9, 2026 covered call sites, constructors, filesystem calls, JSX/TSX components and Python calls. Each fixture contained two valid structures with different formatting plus one comment/string decoy. All 12 expected matches were found with no false positives; each response was 669–707 bytes and took 32–48 ms in that single run. A simple fixed-string `rg` query per fixture found six valid matches, missed six formatting variants and returned six decoys (37–85 bytes, 24–33 ms per query). This demonstrates the intended syntax-sensitive use case, not superiority over carefully constructed regex/manual inspection or measured agent productivity. Literal search remains faster and smaller in these trials; choose structural search for syntax-sensitive lookups.

package/extensions/structural-search/config.mjs

@@ -37,7 +37,7 @@ export function readIntegrations(agentDir) {
             }
         } catch (error) {
             if (error.code === "ENOENT") {
-                return { schema: 1, structuralSearch: { enabled: false } };
+                return { schema: 1, structuralSearch: { enabled: true } };
             }
 
             throw error;

package/package.json

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

package/scripts/specpi.mjs

@@ -105,7 +105,7 @@ Options:
   --skip-package-install  Do not bootstrap Pi or install external Pi packages (also skips browser/structural runtime acquisition).
   --skip-browser-install  Install browser tools but skip the managed Playwright/Chromium runtime.
   --skip-tool-install     Skip DonSeTch and structural-search runtime acquisition.
-  --structural-search=on|off  Opt in to structural search or disable/remove its private runtime; omission preserves the choice.
+  --structural-search=on|off  Enable (default) or disable/remove the private runtime; omission preserves a saved choice.
   --skip-shell            Do not install shell profile functions or edit a shell rc file.
 
 Environment:
@@ -1471,16 +1471,13 @@ async function installOrUpdate(options, update) {
         const integrations = readIntegrationsForOperation(options.structuralSearch);
         const structuralEnabled = options.structuralSearch ?? integrations.structuralSearch.enabled;
         // Bound the output before any runtime/configuration mutation, not only when reading the input.
-        const integrationsText =
-            options.structuralSearch !== undefined || fs.existsSync(integrationsPath)
-                ? serializeIntegrations(
-                      {
-                          ...integrations,
-                          structuralSearch: { ...integrations.structuralSearch, enabled: structuralEnabled },
-                      },
-                      integrationsPath,
-                  )
-                : undefined;
+        const integrationsText = serializeIntegrations(
+            {
+                ...integrations,
+                structuralSearch: { ...integrations.structuralSearch, enabled: structuralEnabled },
+            },
+            integrationsPath,
+        );
         if (!update && previousManifest) {
             throw new Error(`SpecPi is already installed. Run ${CLI} update.`);
         }
@@ -1537,15 +1534,13 @@ async function installOrUpdate(options, update) {
             );
         }
 
-        if (integrationsText !== undefined) {
-            // Back up the owned configuration only, never a whole Pi settings/profile store.
-            if (fs.existsSync(integrationsPath)) {
-                fs.copyFileSync(integrationsPath, path.join(backupDir, "tool-integrations.json"));
-            }
-
-            atomicWrite(integrationsPath, integrationsText, 0o600);
+        // Back up the owned configuration only, never a whole Pi settings/profile store.
+        if (fs.existsSync(integrationsPath)) {
+            fs.copyFileSync(integrationsPath, path.join(backupDir, "tool-integrations.json"));
         }
 
+        atomicWrite(integrationsPath, integrationsText, 0o600);
+
         injectTestFailure("after-structural-runtime");
         const blockFiles = structuredClone(previousManifest?.blockFiles || {});
         blockFiles.agents ||= { existed: pathExists(agentsPath) };