ds4-context-engine 0.3.3 → 0.3.4

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Published prerelease `0.3.0-beta.2` carries forward beta.1's bounded Context Manifest storage, cooperative database leases, metadata-only storage diagnostics, and explicit offline inspect/compact/recover maintenance after successful live maintenance validation. Canonical records, SQLite schema 15, and runtime contracts remain unchanged. npm `beta` points to `0.3.0-beta.2`, `alpha` remains `0.3.0-alpha.5`, `latest` remains `0.2.0`, and the maintenance line targets Pi `0.84.3`.
+> **Project status:** The coordinated `0.3.4` release adds optional anchored editing, post-edit reports, adaptive reads, adaptive artifact budgets and managed local bash jobs. All five switches default to off. It carries forward the stable 0.3 line's persistence, offline storage maintenance, dedicated compaction model and configurable transport retries. Canonical history, SQLite schema 15 and runtime contracts remain unchanged; Pi remains pinned to `0.84.3`. See the [0.3.4 release record](docs/releases/0.3.4.md) for validation and publication status.
 
 ## Why DS4
 
@@ -87,12 +87,12 @@ Install the latest stable public npm package with:
 pi install npm:ds4-context-engine
 ```
 
-The stable `0.2.0` packages (`ds4-context-engine`, `ds4-context-core`, and `ds4-context-reference-adapter`) use the same exact version. Both adapters require the matching core version.
+The three packages (`ds4-context-engine`, `ds4-context-core`, and `ds4-context-reference-adapter`) are released together with the same exact version. Both adapters require the matching core version. See [0.3.4](docs/releases/0.3.4.md) for this release's changes and compatibility.
 
 To dogfood the beta without replacing a global stable installation, pin the exact version in a disposable project:
 
 ```bash
-pi install -l npm:ds4-context-engine@0.3.0-beta.2
+pi install -l npm:ds4-context-engine@0.3.0-beta.3
 ```
 
 Follow the [0.3 beta dogfooding runbook](docs/DOGFOODING_0.3.0_BETA.md); use synthetic data and a dedicated session directory.
@@ -209,7 +209,7 @@ Valid privacy classifications are `normal`, `internal`, `sensitive` and `local-o
 
 ### LLM-callable tools
 
-DS4 registers two model-callable tools:
+DS4 registers two model-callable tools by default:
 
 | Tool | Purpose |
 | --- | --- |
@@ -220,6 +220,24 @@ DS4 registers two model-callable tools:
 
 Canonical Pin and Memory changes append Pi custom entries and reconcile disposable SQLite projections. Project-memory source include/exclude is derived local SQLite policy and never appends a fake canonical entry. See [`docs/CONTEXT_PERSISTENCE_TOOL.md`](docs/CONTEXT_PERSISTENCE_TOOL.md).
 
+**Optional anchored editing:** `/context config set editing.anchored true`, then
+`/reload`, enables a same-name `edit` wrapper. Use `head[upto]tail` in `oldText` to
+replace an inclusive range without repeating its intermediate old content. Exact
+anchors are validated inside Pi's native mutation queue; ordinary calls and diff
+feedback remain native. All edits in a batch containing anchors must match exactly.
+Use per-edit `literal: true` for real marker text.
+Disabled by default; no inference-time forcer or provider change is involved.
+See [`docs/ANCHORED_EDITING.md`](docs/ANCHORED_EDITING.md) for semantics and limits.
+
+**Other optional agent tools:** `editing.postEditReport` adds bounded old/new line
+ranges and updated context; `reading.adaptive` chooses model-window-aware default
+read limits; `artifacts.adaptiveBudget` lowers inline/excerpt caps under context
+pressure; `jobs.enabled` exposes confirmed, session-owned local `bash_job`
+start/status/stop/list operations. All default off and require session reload after
+configuration changes. Jobs are a separate module, not a replacement for `bash`.
+See [`docs/PORTABLE_AGENT_TOOLS.md`](docs/PORTABLE_AGENT_TOOLS.md) for activation,
+limits, privacy and lifecycle behavior.
+
 Learned-ranking feedback and local training are explicit:
 
 ```text
@@ -250,6 +268,16 @@ The following example shows the main configuration groups. Omitted values use th
     "maxProjectTokens": 20000,
     "maxSummaryTokens": 12000
   },
+  "editing": {
+    "anchored": false,
+    "postEditReport": false
+  },
+  "reading": {
+    "adaptive": false
+  },
+  "jobs": {
+    "enabled": false
+  },
   "retrieval": {
     "exact": true,
     "fts": true,
@@ -287,6 +315,7 @@ The following example shows the main configuration groups. Omitted values use th
   },
   "artifacts": {
     "enabled": true,
+    "adaptiveBudget": false,
     "maxInlineToolResultChars": 12000,
     "maxArtifactBytes": 100000000,
     "maxSearchBytes": 50000000,
@@ -477,8 +506,14 @@ scripts             package and release-readiness checks
 - [Roadmap 0.2.0](docs/ROADMAP_0.2.0.md)
 - [Release process](docs/RELEASING.md)
 - [0.2.0 release readiness](docs/RELEASE_READINESS_0.2.0.md)
+- [0.3.4 release notes](docs/releases/0.3.4.md)
+- [0.3.3 release notes](docs/releases/0.3.3.md)
+- [0.3.2 release notes](docs/releases/0.3.2.md)
+- [0.3.1 release notes](docs/releases/0.3.1.md)
+- [0.3.0 release notes](docs/releases/0.3.0.md)
 - [0.2.0 release notes](docs/releases/0.2.0.md)
 - [0.2.0-rc.1 release notes](docs/releases/0.2.0-rc.1.md)
+- [0.3.0-beta.3 prerelease notes](docs/releases/0.3.0-beta.3.md)
 - [0.3.0-beta.2 prerelease notes](docs/releases/0.3.0-beta.2.md)
 - [0.3.0-beta.1 prerelease notes](docs/releases/0.3.0-beta.1.md)
 - [0.3.0-alpha.5 prerelease notes](docs/releases/0.3.0-alpha.5.md)
@@ -493,7 +528,7 @@ scripts             package and release-readiness checks
 
 The original M0–M13 roadmap is complete. `ds4-context-core` contains the compiled runtime-neutral implementation. M14 context-quality metrics, M15 rich symbol indexing, M16 hybrid semantic retrieval, M17 cross-session project memory, M18 learned-ranking shadow evaluation, M19's runtime adapter/conformance kit, and M20 opt-in local KV eligibility/replay are implemented on `main`. Learned active ranking remains promotion-gated, Pi reports local KV as unsupported, and static ranking/native completion stay authoritative on every failure.
 
-The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. Published prerelease `0.3.0-beta.2` carries forward the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md), privacy-safe [compaction](docs/COMPACTION.md) hardening, bounded persisted manifests, per-profile calibration retention, cooperative client leases, storage diagnostics, and recoverable offline maintenance, with successful live maintenance evidence from beta.1. Confirmation, exact targeting, strict summary grounding, Pi fallback, and stable canonical/configuration/SQLite/runtime contracts remain unchanged. The [0.2 readiness record](docs/RELEASE_READINESS_0.2.0.md) remains the compatibility baseline. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
+The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. The stable 0.3 line carries forward the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md), privacy-safe [compaction](docs/COMPACTION.md), bounded persisted manifests, cooperative client leases and recoverable offline maintenance. Version 0.3.4 adds opt-in [anchored editing](docs/ANCHORED_EDITING.md) and [portable agent tools](docs/PORTABLE_AGENT_TOOLS.md), without backend rewind, forced sampling or operational KV integration. Confirmation, provenance, Pi fallback and canonical/configuration/SQLite/runtime contracts remain unchanged. The [0.2 readiness record](docs/RELEASE_READINESS_0.2.0.md) remains the compatibility baseline; the lexical planner stays available as the deterministic fallback.
 
 ## Contributing
 

package/docs/ADR/059-optional-anchored-editing.md

@@ -0,0 +1,51 @@
+# ADR 059 — Optional execution-time anchored editing
+
+Status: Accepted
+
+## Context
+
+DS4's standalone agent supports `head[upto]tail` replacement and an optional
+inference-time marker forcer. The former is portable tool semantics; the latter
+requires backend control over generation state. Pi already provides batch edits,
+mutation serialization, normalization, cancellation and diff feedback.
+
+## Decision
+
+- Add the default-off `editing.anchored` configuration key, gated by the DS4 master
+  switch and loaded through existing trusted configuration handling.
+- Register a same-name `edit` override only when enabled and native edit is not
+  already replaced. Do not introduce an additional tool or force tool activation.
+- Support one marker between nonempty, non-whitespace exact anchors, inclusive
+  replacement and suffix-only tail uniqueness. Add per-edit `literal: true` to
+  escape real marker text. Preserve native edit behavior without marker syntax.
+- Expand anchors using private copies inside native `EditOperations.readFile`,
+  under Pi's own mutation queue, then delegate batch validation and writing to
+  `createEditToolDefinition`. Do not copy Pi's editing implementation or expand in
+  an unqueued `tool_call` hook.
+- Require exact matching for all edits in a batch containing anchors: native
+  fuzzy fallback changes the whole batch's coordinate space and can relocate an
+  exact anchored span. Marker-free calls retain native fuzzy behavior.
+- Keep native normalized ambiguity checks, even when stricter than exact anchor
+  validation. Invalid anchored edits fail closed, without a fallback to a broader
+  match. ADR 008's context-planning fallback is not permission to guess file edits.
+- Preserve native diff results and append compact original-line range metadata.
+  Skip marker-unaware native previews until the actual result diff is available.
+- Restore the native definition if the same extension instance later loads
+  disabled configuration; a fresh disabled load registers no editing override.
+
+## Consequences
+
+No provider change, Pi fork or dependency upgrade is required for execution-time
+anchors. Only the configuration shape enters the portable core; filesystem/tool
+integration stays in the Pi extension. Existing configuration defaults otherwise
+remain unchanged, and the additive compatibility golden is updated.
+
+The adapter relies on native edit reading through the supplied operations before
+matching the provided edit array, while holding its shared queue. Tests against
+Pi 0.84.3 pin that ordering and cancellation behavior. Dependency upgrades must
+re-run these contracts. Other edit overrides, external editors/processes, atomic
+writes and backend generation-state control remain outside the guarantee.
+
+See [usage and limitations](../ANCHORED_EDITING.md). No automatic marker forcer,
+constrained grammar, live configuration activation or measured provider savings
+are part of this decision.

package/docs/ADR/060-optional-portable-agent-tools.md

@@ -0,0 +1,38 @@
+# ADR 060 — Optional portable DS4 agent improvements
+
+Status: accepted and implemented; included in the coordinated 0.3.4 release. Backend integration remains excluded.
+
+## Boundary
+
+Pi remains the agent runtime and JSONL remains canonical history. These changes add optional tool behavior, not another agent loop. No inference rewind, forced sampling, native KV handles, database migration or dependency upgrade is included.
+
+Four independently default-off switches, also gated by `enabled`:
+
+- `editing.postEditReport`: bounded report from the actual native unified patch, including changed old/new ranges, line delta and post-edit context. Works independently of `editing.anchored`.
+- `reading.adaptive`: choose the default `read` limit from the execution-time model window (120 / 240 / 500 lines at <=8192 / <=16384 / larger windows). Explicit limits, images, cancellation and native byte caps remain native. No shared `more` cursor.
+- `artifacts.adaptiveBudget`: lower inline/excerpt limits according to the calibrated context budget after output/safety reserves and estimated fixed overhead. Never increase configured limits. Preserve minimum reference metadata, canonical results, provenance, privacy, atomic tool groups and normal planner fallback. This is an estimate, not a guaranteed fit or reentrant compaction trigger.
+- `jobs.enabled`: opt-in `bash_job` module in this repository, separate from the portable core and existing `bash`. A single start/status/stop/list tool manages local jobs through Pi's public local BashOperations.
+
+## Editing and reading
+
+Do not take over missing or visibly overridden native tools. Restore native definitions when an already-enabled instance loads disabled configuration. Fresh disabled loads register no override. Render the real native diff; report failures must not turn a successful write into an apparent failure. Limit report regions, context and escaped text; never re-read a potentially changed file for reporting. Retain ADR 059's strict mixed-anchor batch behavior.
+
+## Adaptive artifacts
+
+Use provider-facing privacy-sanitized messages only, and the same calibrated model budget as the planner. Keep all configured storage/search caps. Share the available text budget among candidate results, with a metadata floor bounded by the configured maximum. Missing/invalid budget data keeps static behavior. Rebuild uses the conservative adaptive floor so artifacts from earlier small-budget contexts remain reconstructible. No policy values or canonical messages are mutated. Do not replace a result with a larger estimated result.
+
+## Local jobs
+
+- Require an active built-in local `bash`, no conflicting `bash_job`, explicit configuration, project trust, and local UI confirmation for every start. No UI means no start. This separate tool does not inherit other extensions' bash-only permission policies or SDK shell options.
+- Use opaque job IDs, not arbitrary PIDs. Owner is the current session plus the originating branch entry. Status/stop/list never cross that boundary.
+- At most 4 concurrent jobs and 16 retained records. Default timeout 300 seconds, hard maximum 3600 seconds. Cap each log at 8 MiB and stop on overflow or log-write failure.
+- Logs are raw local files in a private temporary directory, not SQLite state. Responses contain bounded quoted head/tail excerpts and a local output path. Keep completed jobs until bounded eviction or session cleanup; explicitly report output truncation and stop reason.
+- Cancellation while start is pending stops the new job. Once start returns, the job has an independent lifetime; cancelling status does not stop it. Stop and shutdown use native process-tree cancellation. No promise of rollback, daemon ownership or restart survival.
+- Stop jobs and remove temporary logs on session replacement, reload and shutdown. Stop jobs made invisible by branch navigation. Compaction preserves processes and appends a bounded canonical metadata snapshot without launching another model turn; status must be refreshed before acting on old snapshots.
+- Completion marks project indexing dirty. Never launch automatic follow-up turns.
+
+## Verification
+
+Cover independent opt-ins/default-off paths, legacy missing config, argument mutation, native matching and line endings, explicit read limits/images/model changes, estimated budgets/provenance/privacy/rebuild, process caps/timeouts/aborts/ownership/cleanup/compaction, and clean-consumer packaging. Linux process tests do not establish successful Windows execution; the native Pi backend owns platform-specific process handling.
+
+Implementation validation: `npm run check` passed 78 files / 485 tests, including real local bash execution, stop and timeout. Quality comparison and persistence schema gates passed. Clean-consumer packaging passed with Pi 0.84.3 and eight real registry scenarios (core 231 files, reference adapter 7, engine 83). Packaging used a staging copy with the canonical root package manifest; pre-existing user `package.json` changes and `.serena/` were excluded. No provider-token/latency benchmark or Windows execution claim is made. That implementation validation preceded release preparation. See the [0.3.4 release record](../releases/0.3.4.md) for final release gates and publication evidence.

package/docs/ADR/README.md

@@ -62,5 +62,7 @@ The initial decisions from the development plan are accepted:
 | 056 | Keep project-memory source exclusion as disposable derived SQLite policy | Accepted |
 | 057 | Derive mutation provenance from the active branch and exclude model-supplied source IDs from V1 | Accepted |
 | [058](058-bounded-manifest-storage.md) | Bound persisted manifests and defer compression to a versioned migration | Accepted |
+| [059](059-optional-anchored-editing.md) | Opt in to anchored edit expansion inside Pi's native mutation queue | Accepted |
+| [060](060-optional-portable-agent-tools.md) | Opt in to edit reports, adaptive reads/results and session-owned local jobs | Accepted |
 
 Each decision will receive a dedicated record when implementation pressure introduces alternatives or consequences not already covered by the development plan.

package/docs/ANCHORED_EDITING.md

@@ -0,0 +1,144 @@
+# Optional anchored editing
+
+DS4 can replace Pi's native `edit` definition with a compatible, opt-in wrapper.
+This is execution-time editing, not a generation-time forcer. It works with any
+provider that can call Pi tools; it does not require a custom inference backend.
+
+## Enable or disable
+
+Default: `editing.anchored: false`. In a trusted project:
+
+```text
+/context config set editing.anchored true
+/reload
+```
+
+Use `--global` on the config command to target the agent-directory configuration.
+As with other DS4 config writes, the active session configuration is not changed
+by `set`/`unset`; it is loaded on session startup/replacement or reload.
+
+When updating a development checkout, rebuild the core (`npm run build:core`)
+and fully restart Pi. Reloading extension TypeScript can retain previously loaded
+compiled core modules. A core configuration without `editing` safely leaves this
+feature disabled, but the updated core must be loaded to recognize the option.
+
+```json
+{
+  "editing": { "anchored": true }
+}
+```
+
+`enabled: false` also disables this override. `context.mode` still controls context
+planning, not explicitly opted-in editing. Project configuration is ignored when
+Pi does not trust the project; global configuration continues to apply.
+
+On a fresh disabled load DS4 does not register `edit` at all. If an enabled
+extension instance later loads disabled configuration, it restores Pi's native
+edit definition, schema and guidelines. Pi has no public `unregisterTool`; a
+reload while disabled removes DS4's registration entirely.
+
+Registration is skipped if native `edit` is unavailable or already owned by
+another extension/SDK tool, with a UI warning when available. DS4 does not enable
+an inactive native edit tool. Only ownership reported by Pi can be checked: SDK
+custom base tools labeled as built-ins cannot be distinguished through this API.
+Do not enable this feature with other edit replacements or remote/sandbox edit
+implementations; the registered wrapper uses local filesystem operations.
+
+## Tool input
+
+The tool name remains `edit`, with `path` and `edits[]`:
+
+```json
+{
+  "path": "src/example.ts",
+  "edits": [{
+    "oldText": "function oldImplementation() {\n[upto]\n}\n// end oldImplementation\n",
+    "newText": "function oldImplementation() {\n  return improved();\n}\n// end oldImplementation\n"
+  }]
+}
+```
+
+Each anchored `oldText` must contain exactly one `[upto]` marker:
+
+- The **head**, before the marker, must occur exactly once in the original file.
+- The **tail**, after the marker, must occur exactly once after the end of the
+  head. The same tail occurring before the head is allowed.
+- Both anchors must contain non-whitespace text. Spaces are significant.
+- Newlines immediately after the marker are separators and are removed from the
+  tail needle, matching DS4's marker-line convention. Other whitespace is not
+  trimmed. Anchors may be inline; full distinctive lines are usually clearer.
+- Replacement is **inclusive**: head, intermediate content and tail are all
+  replaced. Put anchors in `newText` if they should be retained.
+- All edits refer to the original file, not previous replacements in the batch.
+  Overlaps (including mixed ordinary/anchored overlaps), missing or ambiguous
+  anchors and no-op batches are rejected without a write.
+- No 64-byte/two-line threshold applies to manually supplied anchors; those DS4
+  thresholds belong to automatic marker forcing, which is not implemented here.
+
+A marker is special only in `oldText`, never in `newText`. To match literal marker
+text, set `literal: true` **on that edit**:
+
+```json
+{
+  "path": "notes.md",
+  "edits": [{ "oldText": "[upto]", "newText": "range marker", "literal": true }]
+}
+```
+
+Calls without anchored edits use native Pi matching, including its normalized
+fuzzy fallback (also for `literal: true` edits). **Every edit in a batch containing
+anchors must match exactly**, ordinary edits included. Pi's fuzzy fallback changes
+the coordinate space for the entire batch and can relocate an otherwise exact
+anchored span; mixed fuzzy batches therefore fail closed. Re-read and correct the
+ordinary oldText, or perform the ordinary edit separately and re-read before
+anchored edits.
+
+Exact matching uses BOM-free, LF-normalized original content. Expanded spans then
+pass through native batch checks, including Pi's stricter normalized-ambiguity
+check. Thus a range can be rejected even if its literal anchors pass, when the
+expanded text is ambiguous under Pi's normalization. Re-read and disambiguate;
+do not silently broaden the range.
+
+## Execution and feedback
+
+`src/extension/anchored-edit-tool.ts` uses public Pi `createEditToolDefinition` and
+`EditOperations`. Its per-call read operation expands anchors only after native
+edit has entered `withFileMutationQueue`. Native edit then performs batch matching,
+overlap checks, cancellation checks, BOM/line-ending restoration, writing and
+diff generation. It is deliberately **not** a `tool_call` preflight expansion:
+there is no unqueued read followed by a later queued write.
+
+Expansion uses private argument copies: the full old span is not inserted into
+canonical tool-call arguments or sent back as an expanded input. Native results
+and diff/patch details remain available, plus a compact text report of anchored
+ranges in original line numbers. Canonical result details can still contain old
+text through native diffs; this is not an output privacy/filtering feature.
+
+The native TUI matcher cannot preview marker syntax. Anchored calls therefore
+skip its pre-execution preview and display the **actual native result diff** after
+execution. Ordinary edits retain their native preview behavior.
+
+The shared Pi queue serializes cooperating edits/writes in the same runtime,
+including symlink aliases. It is not a cross-process file lock, transaction with
+external editors, atomic filesystem write or rollback guarantee. Cancellation
+retains native behavior; once a write has begun it may still complete. Existing
+`tool_call`/`tool_result` hooks continue to see the `edit` tool, not a new tool name.
+Hooks that interpret `oldText` themselves must understand the opt-in syntax.
+
+## Scope and verification
+
+The implementation targets the project's Pi **0.84.3** dependency. No dependency
+upgrade, provider grammar, streaming interception, KV rewind or forced continuation
+is included. The reference adapter does not implement this Pi editing capability.
+
+Tests cover exact matching, suffix-only tail uniqueness, overlapping matches,
+malformed markers, literal escaping, mixed batches, fuzzy-fallback compatibility,
+BOM/CRLF/Unicode, unchanged arguments, result diffs, cancellation, queue ordering,
+symlinks, permissions, working-directory selection and session-bound registration.
+The package smoke check also inspects the real Pi tool registry offline with the
+flag absent, enabled, master-disabled and enabled while native edit is inactive
+or unavailable.
+A deterministic large-block fixture compares serialized request bytes and verifies
+the same output as native editing. Real-provider reliability, token usage and
+latency improvements have **not** been measured; shorter oldText can save generated
+text, while the opt-in tool schema/instructions also add prompt overhead.

package/docs/ARCHITECTURE.md

@@ -165,6 +165,44 @@ Pin and Memory mutations resolve provenance from the active Pi branch, revalidat
 
 Historical tool arguments and results are a provider-egress surface even when general privacy is disabled. A dedicated guard removes content, query, key, reason, paths and raw errors while preserving only action linkage and safe IDs/revisions. Provenance IDs and source paths are runtime-derived; the model cannot supply them in the V1 schema. Post-append failures distinguish an indeterminate append from a known canonical commit with pending projection, so callers are never encouraged to retry blindly.
 
+## Optional anchored editing
+
+After trusted configuration loads at `session_start`, `editing.anchored` can
+register a same-name native `edit` wrapper (default off, also gated by `enabled`).
+The Pi extension resolves exact `head[upto]tail` ranges inside the native edit read
+operation, under Pi's shared file mutation queue, then delegates batch checks,
+cancellation, BOM/EOL handling, writing and diffs to native edit. Expansion never
+rewrites canonical tool-call arguments. Calls without anchors retain native fuzzy
+matching; every edit in an anchored batch must match exactly to prevent native
+fuzzy rematching from moving its ranges. Invalid anchored edits fail closed.
+No inference-state control is involved.
+See [anchored editing](ANCHORED_EDITING.md) and [ADR 059](ADR/059-optional-anchored-editing.md).
+
+## Other optional portable agent tools
+
+`editing.postEditReport` derives bounded old/new coordinates, line deltas and
+updated context from the actual native patch, independently of anchored editing.
+`reading.adaptive` wraps native read with execution-time model-aware default line
+limits; explicit limits and image/byte handling stay native. Both wrappers restore
+native definitions when disabled and do not initially claim other tool overrides.
+
+`artifacts.adaptiveBudget` is a pure portable-core policy applied per context to
+privacy-prepared messages. It uses the calibrated planner budget and estimated
+fixed overhead to lower inline/excerpt caps, never raises configured limits, and
+preserves source identities and canonical history. Rebuild uses a conservative
+floor to reconstruct earlier adaptive references. Normal planner fallback remains
+responsible for oversized mandatory context.
+
+`src/tools/bash-job-manager.ts` and `src/extension/bash-job-tool.ts` form a separate
+optional local job module. It delegates process execution/cancellation to Pi's
+public BashOperations, limits concurrency/log storage, enforces session/branch
+ownership and requires local confirmation for starts. Jobs survive compaction but
+not session replacement/reload/shutdown; compaction appends bounded metadata only.
+There is no new agent loop, SQLite state, automatic model turn or backend KV control.
+
+All new switches are default-off and master-gated. See [portable agent tools](PORTABLE_AGENT_TOOLS.md)
+and [ADR 060](ADR/060-optional-portable-agent-tools.md).
+
 ## Boundaries
 
 Dependency direction is one-way:

package/docs/PORTABLE_AGENT_TOOLS.md

@@ -0,0 +1,86 @@
+# Optional portable agent tools
+
+These features are separate opt-ins, also gated by the DS4 master `enabled` switch. They do not implement inference rewind, forced sampling, or native KV-cache integration. Pi remains the agent runtime.
+
+Enable only the features you want, then reload:
+
+```text
+/context config set editing.postEditReport true
+/context config set reading.adaptive true
+/context config set artifacts.adaptiveBudget true
+/context config set jobs.enabled true
+/reload
+```
+
+All four default to `false`. Configuration writes apply on the next session load, not immediately. The default target is the trusted project configuration; add `--global` for the agent-directory file. Disable with the same commands using `false`, then reload.
+
+## Post-edit reports
+
+`editing.postEditReport` works with native ordinary edits, independently of `editing.anchored`. Enable both to combine reports with [`[upto]` ranges](ANCHORED_EDITING.md).
+
+After a successful edit, the tool result content and details include:
+
+- actual old/new changed ranges from Pi's native unified patch;
+- total line delta and cumulative shift for subsequent lines;
+- bounded numbered context from the updated content, encoded as quoted JSON data.
+
+Regions combine nearby changes in the same native patch hunk. Zero-length ranges identify insertion/deletion boundaries. Coordinates refer to the completed write, not future file state. Reports include at most six regions and six short context lines per region; rendered report text stays below 6000 characters. The native patch/diff remains available and the TUI continues to display the native diff. There is no separate file read after the write and no change to matching or mutation queues. If reporting fails, the successful edit result is retained rather than encouraging a duplicate write.
+
+## Adaptive reads
+
+`reading.adaptive` changes only the default line limit of the native `read` tool:
+
+| Execution-time model window | Default lines |
+| --- | ---: |
+| <= 8192 tokens | 120 |
+| <= 16384 tokens | 240 |
+| larger | 500 |
+| missing/invalid model window | native default |
+
+Explicit positive integer `offset`/`limit` values are honored; native byte limits can still shorten a response. Images, path resolution, access errors and cancellation remain native. The model is checked on each execution, so switching models does not require reload. Arguments are copied, not rewritten in canonical tool calls.
+
+Use the native continuation notice, e.g. `offset=121`, to read more. There is deliberately no shared `more` cursor, which could become ambiguous after concurrent reads, branching or compaction. This does not reduce the native reader's full-file I/O or memory use.
+
+Both file overrides skip initial registration if their built-in tool is missing or visibly overridden. Disabling an already-enabled instance restores the native definition; fresh disabled loads register nothing. Compatibility is tested against the project's Pi dependency, currently `0.84.3`. Custom SDK/remote filesystem integrations are not covered by these local wrappers.
+
+## Adaptive tool-result/artifact budget
+
+`artifacts.adaptiveBudget` operates only where artifact offload already operates: DS4 enabled, managed context, and artifact storage enabled/available.
+
+The per-context policy uses the same calibrated active input budget as the planner, after output reserve and safety margin. It subtracts estimated system/tool-schema overhead, other messages and non-text blocks, then shares 75% of remaining capacity among candidate text results. It can only lower `artifacts.maxInlineToolResultChars` and `artifacts.excerptChars`, never raise them. The reference-metadata floor is 1600 characters or the configured inline maximum, whichever is smaller.
+
+This is estimated budgeting, not a tokenizer-exact fit guarantee. Irreducible metadata, errors, missing provenance or unavailable storage can still leave a context oversized. The existing planner and fallback behavior remain responsible; there is no recursive `ctx.compact()` call inside the context hook.
+
+Canonical Pi messages stay unchanged. Only privacy-prepared provider-facing text is transformed, with the original tool identity, source IDs and non-text blocks preserved. Artifact storage/search caps and branch/privacy checks remain unchanged. Rebuild uses the conservative adaptive floor so earlier small-budget artifacts remain reconstructible; consequently it may reconstruct more small artifacts than the fixed-threshold policy. A result is not replaced with a larger estimated result.
+
+## Managed local bash jobs
+
+The `bash_job` tool is implemented in a separate optional module, not in the portable core. It does not replace `bash` and is not a new agent loop or a separate published package.
+
+Examples of tool arguments:
+
+```json
+{"action":"start","command":"npm test","timeout":300}
+{"action":"list"}
+{"action":"status","id":"<returned-job-id>"}
+{"action":"stop","id":"<returned-job-id>"}
+```
+
+### Authorization and execution
+
+- Requires an active built-in local `bash`, an unclaimed `bash_job` name, a trusted project, and local UI confirmation for every start. Missing UI or refused confirmation means no command starts. Tool-call arguments are revalidated, and the confirmed command/cwd/timeout are snapshotted.
+- Executes in the current working directory using Pi's public local BashOperations. It **does not inherit** custom bash-only permission hooks, remote/sandbox behavior, SDK shell settings/command prefixes, or session-specific `PI_*` injection. It must not be used to bypass those controls. The confirmation explicitly identifies the local execution boundary.
+- Status/stop/list use opaque IDs owned by the current session and originating branch entry, never arbitrary PIDs. Stop remains available for owned jobs even if bash is later deactivated.
+- Four running jobs maximum; sixteen retained records maximum. Oldest completed records/logs are evicted first. Timeout defaults to 300 seconds; valid range is 1–3600 seconds.
+
+### Output and lifecycle
+
+Logs combine stdout/stderr in native arrival order. Each private local log is capped at 8 MiB; reaching the cap or a write error stops the job. Status returns at most 512 bytes of head plus 512 bytes of non-overlapping tail, quoted in JSON, and the local output path. For larger logs, read that path while the session remains open. `outputTruncated` also indicates omitted middle output; `status=output-limit` distinguishes a capped log. A nonzero exit code is reported, not hidden.
+
+Successful start returns immediately; subsequent agent cancellation does not silently kill the independently running job. Cancelling a status request does not stop it. Use `stop` explicitly. Completion marks project indexing dirty but does not trigger another model turn.
+
+Jobs survive compaction. The extension appends a bounded canonical **metadata snapshot** after compaction, without command/output text or a follow-up model request. Refresh status before acting on any old snapshot. Branch navigation stops jobs no longer visible from the new branch; ancestor-owned jobs remain visible. Session replacement, reload and graceful shutdown stop jobs and remove their logs. State is not persisted in SQLite, Memory or Pins and is not restored after restart.
+
+Native Pi handles process-tree cancellation. There is no rollback of command side effects and no guarantee of controlling deliberately escaped daemons. Forced process termination/crashes can leave temporary logs; abrupt-exit cleanup is not guaranteed. Raw logs can contain secrets: do not publish or persist them blindly. Linux tests do not establish Windows execution success.
+
+Architecture: [ADR 060](ADR/060-optional-portable-agent-tools.md).

package/docs/releases/0.3.3.md

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.3
 
-Status: candidate, not yet published.
+Status: published 2026-09-04 as stable, printed under the npm `latest` dist-tag, tagged `v0.3.3`.
 
 This release adds a configurable transport retry policy for compaction summary requests on top of the 0.3.2 stable candidate. It carries forward 0.3.2 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics.
 
@@ -43,7 +43,7 @@ ds4-context-reference-adapter
 ds4-context-engine
 ```
 
-Both adapters depend exactly on `ds4-context-core@0.3.3`. Publication uses npm's default `latest` tag for all three packages. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+Both adapters depend exactly on `ds4-context-core@0.3.3`. Publication uses npm's default `latest` tag for all three packages: `latest` now resolves to `0.3.3` (previously `0.3.2`), `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
 
 ## Candidate validation
 
@@ -58,3 +58,23 @@ Local candidate verification on Node.js `26.5.1`:
 - Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.3`.
 
 Validation-only CI is recorded below with the release commit. Exact registry verification and the annotated tag are recorded after execution.
+
+## Validation-only CI
+
+Release commit `5d636cc` (chore(release): prepare 0.3.3); CI run `33921584110` on Node `22.19.0` and `24.x`. The first Node 22.19.0 attempt hit a one-off `upgrade-rebuild` migration test timeout (5 s default) on the shared runner; the exact same test passes locally and on the re-run, and the rerun completed `success` on both Node versions.
+
+## Registry verification and tag
+
+Published manually in dependency order with npm's default `latest` tag after `npm whoami` confirmed `alucard_24`:
+
+- `ds4-context-core@0.3.3`; shasum `5db4c81a9c6a8861bf6612d499abec7fb576e411`;
+- `ds4-context-reference-adapter@0.3.3`; shasum `7a251de9735968776d21ed16a2e10786ea2bc2ef`;
+- `ds4-context-engine@0.3.3`; shasum `cb107f9e28d89e860b3b05118f374a9c9969b58c`.
+
+`npm run registry:check -- 0.3.3` passed: fresh-install exact core/adapters, public core/KV exports, compiled reference conformance, packaged quality corpus, installed `ds4-context-storage` CLI shim probe, and published Pi extension startup through isolated offline RPC state. The first check attempt hit a stale npm cache ETARGET for `ds4-context-engine@0.3.3`; a direct registry query confirmed all three artifacts and dist-tags, and the retry passed.
+
+npm dist-tags for all three packages: `latest=0.3.3`, `beta=0.3.0-beta.3`, `alpha=0.3.0-alpha.5`, `rc=0.2.0-rc.1`.
+
+Annotated tag `v0.3.3` was pushed and the GitHub Release was created:
+
+https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.3

package/docs/releases/0.3.4.md

@@ -0,0 +1,63 @@
+# DS4 Context Engine 0.3.4
+
+Status: release candidate; publication pending final validation and CI.
+
+## Added since 0.3.3
+
+Five independent opt-ins, all default-off and gated by the master `enabled` switch:
+
+- **`editing.anchored`**: exact, inclusive `head[upto]tail` replacements, expanded under Pi's native mutation queue. Literal escaping, mixed-batch exactness, native cancellation/line endings and real result diffs are preserved. No generation-time marker forcing.
+- **`editing.postEditReport`**: bounded changed-line ranges, line delta and numbered updated context derived from the actual native patch, without rereading the file. Works independently of anchored editing.
+- **`reading.adaptive`**: execution-time model-aware default read windows of 120/240/500 lines. Explicit limits, images and native byte caps remain native.
+- **`artifacts.adaptiveBudget`**: per-context estimated caps can only lower configured inline/excerpt limits. Privacy-prepared provider context, source provenance, non-expanding replacements and conservative artifact rebuild are covered.
+- **`jobs.enabled`**: separate local `bash_job` start/status/stop/list tool with trusted-project and local UI confirmation for every start, session/branch ownership, bounded output/concurrency/timeouts and lifecycle cleanup. Jobs survive compaction with a metadata-only reminder, not session replacement/reload/shutdown.
+
+See [anchored editing](../ANCHORED_EDITING.md), [portable agent tools](../PORTABLE_AGENT_TOOLS.md), [ADR 059](../ADR/059-optional-anchored-editing.md) and [ADR 060](../ADR/060-optional-portable-agent-tools.md).
+
+## Safety and compatibility
+
+Pi JSONL remains canonical and append-only; SQLite remains disposable/rebuildable with schema `15`. No live database intervention, provider/backend integration or Pi upgrade is part of this release.
+
+Unchanged contracts: `ds4-context-config-v1`, `runtime-adapter-v1`, `ds4-context-persistence-tool-v1`, `ds4-context-persistence-result-v1`. Pi remains pinned to `0.84.3`; Node.js requirement remains `>=22.19.0`.
+
+Local tool wrappers must not be combined with remote/sandbox replacements. `bash_job` does not inherit bash-only permission hooks or SDK shell settings; its confirmation explicitly identifies this boundary. Stop does not roll back shell side effects or guarantee ownership of escaped daemons. Linux execution tests do not establish Windows correctness. Adaptive budgets are estimates; real-provider token savings, latency and reliability have not been measured. No operational KV reuse, rewind, forced sampling or marker insertion is added.
+
+## Update and enable
+
+After publication, install the exact package and fully restart Pi to load the matching compiled core:
+
+```bash
+pi install npm:ds4-context-engine@0.3.4
+```
+
+In a trusted project, enable only the features you want:
+
+```text
+/context config set editing.anchored true
+/context config set editing.postEditReport true
+/context config set reading.adaptive true
+/context config set artifacts.adaptiveBudget true
+/context config set jobs.enabled true
+/reload
+/context config show
+```
+
+Add `--global` to each `set` to target the agent-directory configuration instead of the project file. Trusted project settings take precedence. Configuration writes do not change the active session until reload/startup. Use `false` to disable. The DS4 master `enabled` switch must also be true.
+
+## Package policy and validation
+
+All three packages use `0.3.4`: `ds4-context-core`, `ds4-context-reference-adapter`, `ds4-context-engine`. Both adapters depend exactly on `ds4-context-core@0.3.4`. Publication is manual in that order using npm's stable `latest` tag. GitHub Actions remains validation-only, with OIDC and package-write permissions denied.
+
+Candidate validation on Node.js `26.5.1`, from a sanitized release source with a fresh `npm ci`:
+
+- `npm run check`: **78 files / 485 tests passed**, including native edit queue/matching regressions, independent opt-ins and real local bash execution/stop/timeout.
+- `npm run quality:compare`: passed; frozen-corpus candidate score `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: passed, `1266` bytes / `317` estimated tokens (limits `1500` / `320`).
+- `npm run latency:check` against exact `ds4-context-core@0.1.2`: passed; disabled-planning p95 ratio `0.885863`, maximum `1.1`. This is not a provider latency/savings measurement.
+- `npm run pack:check`: clean-consumer core **231 files**, reference adapter **7**, engine **84**, with eight real offline Pi registry scenarios.
+- All three `npm pack --dry-run --json` inventories and `git diff --check` passed.
+- Versions, exact core dependencies, lockfile and runtime version constants are synchronized. No dependency upgrade was performed.
+
+Pre-existing local `allowScripts` additions and `.serena/` are excluded from release commits and public packages.
+
+The initial CI run `33965143704` on candidate `4e665e3` passed Node `22.19.0`. Node `24.x` exceeded the default 5-second timeout in the existing disk-backed schema-v10 upgrade fixture (484 tests passed, one timeout). That individual correctness test now has a bounded 15-second timeout, with all assertions unchanged; no runtime/storage behavior changed. Final CI and exact registry evidence will be recorded after execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.3.3"
+    "ds4-context-core": "0.3.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",