@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -34,6 +34,7 @@ gjc ultragoal create-goals --brief "<brief>"
 gjc ultragoal create-goals --brief-file <path>
 gjc ultragoal complete-goals
 gjc ultragoal complete-goals --retry-failed
+gjc ultragoal quality-gate validate --quality-gate-json <quality-gate-json-or-path> [--goal-id <id>] [--json]
 gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --quality-gate-json <quality-gate-json-or-path>
 gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
 gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>"
@@ -193,7 +194,7 @@ When delegating:
 - Give each `executor` bounded targets and explicit acceptance criteria, and keep checkpoint/goal-state ownership in the leader.
 - Parallelize only across genuinely different sub-domains/modules/systems; sequence anything with a real dependency or shared-surface overlap.
 - Work within a single domain/subsystem stays with the leader as direct edits — do not split one cohesive change across subagents, and do not over-delegate trivial work.
-- After integrating delegated slices, run `architect` / `critic` review lanes; worker agents never mutate `.gjc/_session-{sessionid}/ultragoal` or call goal tools.
+- After integrating delegated slices, you MAY run `architect` / `critic` review lanes for early signal, but treat them as **advisory**: the canonical review is the boundary cohort gate below, and a slice-level lane never substitutes for it or its verdict. Skip slice review entirely when the boundary cohort will cover the same change set shortly. Worker agents never mutate `.gjc/_session-{sessionid}/ultragoal` or call goal tools.
 
 When delegating with native subagents, an await timeout only limits the leader's wait. It is not subagent failure evidence and must not be used as a cancellation reason; inspect or continue independent work, and cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong.
 
@@ -223,21 +224,19 @@ Before workers start, each per-slice coordination contract MUST name the target
 
 For failed, timed-out, or contract-violating slices, record durable ledger evidence; preserve successful terminal slices only when safe; and reassign, retry, or collapse the invalid work to serial execution under an updated contract. Completion after parallel work still requires terminal worker evidence, leader integration, targeted verification, and the existing cleaner + architect + executor QA/red-team gate before checkpoint complete.
 
-### Runtime-backed pipelined scheduling
-
-Sequential execution remains the default. Ultragoal may use runtime-backed pipelined scheduling only when `goals.json` metadata proves original-plan independence and disjoint target files/surfaces for the prior and next goals. This is a leader-owned Ultragoal runtime contract, not hidden Team scheduling and not a substitute for the native executor parallelism contract above.
+Team remains explicit and separate: Team is not auto-launched, not a hidden pipeline scheduler, and never owns Ultragoal goals, checkpoints, or ledger state.
 
-Pipeline metadata is explicit-only: create eligible goals with `gjc ultragoal create-goals --goal-metadata-json '<json>'` or the equivalent runtime `createUltragoalPlan({ goalMetadata })` input. Brief-only or missing metadata remains valid but non-eligible and falls back to ordinary sequential scheduling. The initial pipeline contract is **aggregate mode only**; per-story mode remains sequential until a separate UX/state contract exists.
+## Boundary verification (aggregate default)
 
-The full lifecycle commands (`start-pipeline-overlap`, `join-pipeline-overlap`, `rebaseline-pipeline-overlap`) and the fail-closed overlap rules — at most one eligible next goal per join window, G(N) remains active until a clean join, quarantine and re-baseline on dirty joins or lost handles, complete checkpoints fail closed on open overlaps or unattributable change-set paths — are specified in the internal `pipeline-validation-contracts` fragment (`skill-fragments/ultragoal/pipeline-validation-contracts.md`). Load that fragment before operating an overlap; the runtime enforces its rules verbatim.
+Heavyweight review runs **once per boundary**, not once per story. In aggregate mode the whole required-goal set is one implicit boundary by default: every checkpoint before the run's final required goal may present the lightweight `deferredToBatch` gate, and only the final goal carries the full strict gate. Nothing needs to be declared to get this — it is the default.
 
-Team remains explicit and separate: Team is not auto-launched, not a hidden pipeline scheduler, and never owns Ultragoal goals, checkpoints, or ledger state.
+Per-subgoal verification is **agent-chosen**. The runtime does not dictate which lanes an intermediate story runs; it enforces only that the declaration matches the evidence. List the lanes you actually ran in `deferredToBatch.ranLanes` (`targetedVerification`, and optionally `aiSlopCleaner` / `iteration`). A declared lane with no evidence is rejected, submitted evidence for an undeclared lane is rejected, and `ranLanes` can never claim `architectReview` or `executorQa` — a deferred gate structurally cannot carry review evidence, so those lanes always belong to the boundary. `targetedVerification` remains mandatory; the ai-slop-cleaner pass and a full verification rerun are boundary duties, not per-subgoal duties.
 
-## Validation batches (aggregate-only)
+Deferring never manufactures approvals: a `deferredToBatch` gate still cannot contain `architectReview`, `executorQa`, or `validationBatchClose`, and the boundary gate keeps every existing fail-closed rule.
 
-Validation batches let several aggregate-mode goals that share one review/QA boundary defer their heavyweight architect + executor QA/red-team review to a single **final member**, while each non-final member still proves targeted verification and cleanup. Validation batches are **aggregate-only**, **explicit-only**, and **fail-closed**. They are created only through `--validation-batch-json`; there is no inference from brief prose and no per-story batching.
+### Validation batches (explicit phase/module boundaries)
 
-Batches and #1701 pipeline metadata/overlap are **mutually exclusive**: `--validation-batch-json` and `--goal-metadata-json` cannot be combined, and a goal may not carry both `validationBatch` and eligible `pipelineMetadata`. There is no batch/pipeline mixing.
+When one ledger is large enough that a single end-of-run boundary is too coarse, use an explicit validation batch to subdivide it into phase/module boundaries, each with its own final member. Validation batches are **aggregate-only**, **explicit-only**, and **fail-closed**. They are created only through `--validation-batch-json`; there is no inference from brief prose, no per-story batching, and no other batching input path.
 
 Create a batch explicitly:
 
@@ -245,14 +244,14 @@ Create a batch explicitly:
 gjc ultragoal create-goals --brief-file <path> --validation-batch-json '[{"schemaVersion":1,"batchId":"VB001","memberIds":["G001","G002","G003"],"finalGoalId":"G003"}]'
 ```
 
-Checkpoint contract summary — the full contract lives in the `pipeline-validation-contracts` fragment (`skill-fragments/ultragoal/pipeline-validation-contracts.md`); load it before checkpointing any batch member:
+Checkpoint contract summary — the full contract lives in the `validation-batch-contracts` fragment (`skill-fragments/ultragoal/validation-batch-contracts.md`); load it before checkpointing any batch member:
 
-- **Non-final members** checkpoint `complete` with a single top-level `deferredToBatch` quality gate (kind `validation-batch-deferred`) proving targeted verification, an ai-slop-cleaner pass, a rerun iteration, and a cumulative-since-base change set — never `architectReview`, `executorQa`, or `validationBatchClose`; deferring never manufactures fake review approvals.
+- **Non-final members** checkpoint `complete` with a single top-level `deferredToBatch` quality gate (kind `validation-batch-deferred`) proving targeted verification, a declaration-matched lane set, and a cumulative-since-base change set — never `architectReview`, `executorQa`, or `validationBatchClose`; deferring never manufactures fake review approvals.
 - **The final member** (`finalGoalId`) checkpoints `complete` with the normal full strict gate PLUS a top-level `validationBatchClose` proof covering all members; out-of-order close is rejected, close state is append-only proof on the final member only, and batch invalidation is fail-closed.
 
 ### Intra-goal validation-lane parallelism
 
-Within a single goal (including a single-goal run or one validation-batch member), architect review and the executor QA/red-team lane MAY run in parallel, but only on the same **frozen post-cleaner change set**: run the ai-slop-cleaner to a zero-blocker pass and rerun verification first, then hand both lanes the identical frozen change-set summary. Parallel architect + executor QA/red-team lanes must **join before checkpoint** — neither lane may checkpoint independently. Fall back to **sequential** lanes when code is still changing, when the two lanes would see divergent snapshots, when the red-team lane depends on architect fixes, or when architect findings gate the QA scope.
+Cohort lanes are parallel by construction: the boundary gate freezes one `sourceHash` first, so `cleaner`, `architect`, and `qa` can run concurrently against the identical immutable snapshot and then join. Fall back to **sequential** lanes only when code is still changing (nothing can be frozen yet), when the red-team lane depends on architect fixes, or when architect findings gate the QA scope. Either way the lanes must **join before checkpoint** — no lane checkpoints independently, and repair work starts only after the join.
 
 ## Use Ultragoal and Team together
 
@@ -276,13 +275,15 @@ The completion-gate cleanup sweep is driven by `ai-slop-cleaner`, an internal Ul
 - The leader and a leader-spawned `executor` own all fixes; the cleaner reruns until zero blocking findings remain. Advisory findings live in the gate report only.
 - Recursion guard: it must not spawn nested `ralplan`/`team`/`deep-interview`/`ultragoal`; broad or architectural findings are handed back to the leader as review blockers.
 
-## Mandatory completion cleanup and review gate
+## Boundary completion cohort gate
 
-An ultragoal story cannot be checkpointed `complete` until the active agent has run the quality gate. The gate is plan-first, contract-driven, and surface-based:
+The heavyweight gate runs **once per boundary generation**, not once per story and not once per review pass. Intermediate stories use the lightweight deferred gate above; this section applies at the boundary (the run's final required goal, or an explicit batch's final member).
 
-1. Run targeted implementation verification for the story.
-2. Run the internal ai-slop-cleaner skill fragment as the cleanup sweep on the story's changed files only, so only clean code reaches the review and red-team lanes. It is a read-only detector that emits an `AI SLOP CLEANUP REPORT`; if there are no relevant edits it still runs and records a passed/no-op report. Every BLOCKING cleaner finding is a completion blocker: the leader spawns an `executor` to fix blocking findings only, then reruns the cleaner until blocking findings are zero. Advisory findings are included in the gate report only and are not written to the Ultragoal ledger. Carry the report through the existing `qualityGate.iteration.evidence` field; do not add a new top-level quality-gate key.
-3. Rerun verification after the cleaner pass so reviewed evidence covers the cleaned code.
+One generation freezes the change set and reviews it exactly once:
+
+1. Run implementation verification for the boundary's cumulative change set.
+2. **Freeze the change set.** Compute one immutable `sourceHash` over the reviewed source. Every lane in this generation inspects that same frozen snapshot; a lane verdict carrying a different `sourceHash` is rejected.
+3. **Run the cohort lanes on the frozen snapshot** — at most one `cleaner`, one `architect`, and one `qa` lane per generation. They may run in parallel because they share the frozen source; a second architect or QA lane in the same generation is rejected. The `cleaner` lane is the internal ai-slop-cleaner skill fragment run over the frozen change set: a read-only detector that emits an `AI SLOP CLEANUP REPORT`, and it still runs and records a passed/no-op report when there are no relevant edits. Its BLOCKING findings join the cohort findings rather than starting their own fix loop; advisory findings are included in the gate report only and are not written to the Ultragoal ledger.
 4. Delegate an `architect` review covering all three lanes:
    - architecture-side: system boundaries, layering, data/control flow, operational risks.
    - product-side: user-visible behavior, acceptance criteria, edge cases, regressions.
@@ -295,17 +296,19 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - API/package surfaces require a real artifact file or typed receipt whose artifact `kind` contains one of `api`, `package`, `consumer`, `black-box`, or `test-report`; examples: `api-package-test-report`, `package-consumer-report`, `black-box-api-receipt`. Algorithm/math surfaces require a real artifact file or typed receipt whose artifact `kind` contains one of `property`, `boundary`, `edge`, `adversarial`, `failure`, `math`, `algorithm`, or `test-report`; examples: `property-test-report`, `algorithm-boundary-report`. Bare `inlineEvidence` text alone is not sufficient for any surface.
    - The mandatory **computer-use** red-team suite (`kill-switch-bypass`, `suspended-enforcement`, `permission-revoked`, …) is conditional, not universal: require it only when computer/desktop control is genuinely part of the product surface being dogfooded. For every other product type, prove the change through the matching live surface instead — browser-use automation for web/GUI, bash/CLI live invocation or argv replay for CLI, and real artifacts or typed receipts for API/package/algorithm/math. Editing docs, prompts, or skills that merely mention computer-use does not by itself make the computer-use suite applicable; pick the red-team surface that matches what the change actually ships.
 7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
-8. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
-9. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
+8. **Join before repairing.** Fold all three lane verdicts and the final code review into the strict gate under `iteration.reviewCohort` (`reviewGeneration`, `sourceHash`, `joined: true`, and the three `lanes`). No lane may checkpoint on its own, and no fix work starts until the findings are joined. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, the cohort is joined with every lane clean and hash-bound, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
+9. If the joined findings contain any blocker, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record **one consolidated blocker batch** for all findings from the whole cohort instead of one story per lane:
    ```sh
-   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<architect/executor findings>"
+   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<joined cohort findings>"
    ```
-10. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
-11. Only after the loop is clean, checkpoint the story as complete with a structured quality gate. The checkpoint creates a receipt in `ledger.jsonl`; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before the agent calls `goal({"op":"complete"})` to reconcile the inline UX goal state.
+10. One consolidated fix batch produces exactly **one new generation**. Re-freeze the fixed source as a new `sourceHash`, bump `reviewGeneration`, and set `deltaOnly: true` with `priorGenerationSourceHash` and the `deltaPaths` actually changed. Generation 2+ reviews are **delta-only**: they may not pull in unrelated scope without an explicit `scopeExpansion` carrying `severity`, `novelty`, and `justification`. Repeat until a generation joins clean.
+11. Only after a generation joins clean, checkpoint the story as complete with a structured quality gate. The terminal critic runs **once** on that final joined generation; when `criticReview.sourceHash` is present it must match the cohort's `sourceHash`. The checkpoint creates a receipt in `ledger.jsonl`; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before the agent calls `goal({"op":"complete"})` to reconcile the inline UX goal state.
 
 While an Ultragoal run is active, the `ask` tool is blocked for all agents. Record unresolved review decisions as durable blockers with `gjc ultragoal record-review-blockers` instead of prompting interactively.
 
-The native `checkpoint --status complete` command rejects missing or shallow gates. `--quality-gate-json` must include:
+The native `checkpoint --status complete` command rejects missing or shallow gates, and reports **all** structural, evidence, surface, cohort, and declaration errors in one run rather than one per attempt. Each diagnostic carries a stable `path`, a stable machine-readable `code`, and a human `message`.
+
+Validate before you checkpoint. `gjc ultragoal quality-gate validate --quality-gate-json <json-or-path> [--goal-id <id>] [--json]` applies exactly the same rules as `checkpoint --status complete` (including deferred-vs-boundary gate selection and artifact existence checks) but is strictly read-only: it never touches `goals.json`, `ledger.jsonl`, or goal state. It exits non-zero with the full diagnostics list when invalid, so authoring a gate is one pass instead of an edit/retry loop. `--quality-gate-json` must include:
 
 ```json
 {
@@ -344,6 +347,16 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
     "evidence": "blockers absent or resolved and the full loop was rerun cleanly",
     "fullRerun": true,
     "rerunCommands": ["bun test:e2e", "bun test:red-team"],
+    "reviewCohort": {
+      "reviewGeneration": 1,
+      "sourceHash": "sha256:<frozen change-set hash every lane inspected>",
+      "joined": true,
+      "lanes": {
+        "cleaner": { "status": "passed", "sourceHash": "sha256:<same>", "evidence": "AI SLOP CLEANUP REPORT: zero blocking findings", "blockers": [] },
+        "architect": { "status": "CLEAR", "sourceHash": "sha256:<same>", "evidence": "architecture/product/code review of the frozen set", "blockers": [] },
+        "qa": { "status": "passed", "sourceHash": "sha256:<same>", "evidence": "e2e + red-team run against the frozen set", "blockers": [] }
+      }
+    },
     "blockers": []
   }
 }

package/src/defaults/gjc/skills/ultragoal/validation-batch-contracts.md

@@ -0,0 +1,12 @@
+# Ultragoal Validation-Batch Contracts Fragment
+
+Internal Ultragoal sub-skill fragment (`kind: "skill-fragment"`, parent skill `ultragoal`, installed at `skill-fragments/ultragoal/validation-batch-contracts.md`). The Ultragoal leader loads it on demand before checkpointing a validation-batch member; it is never user-facing, not slash-command discoverable, and never resolvable through `skill://`. The runtime enforces every rule below verbatim and fails closed.
+
+## Validation-batch checkpoint contract
+
+- **Non-final members** checkpoint `complete` with a single top-level `deferredToBatch` quality gate (kind `validation-batch-deferred`): a passing `targetedVerification` lane plus a cumulative-since-base change set. An ai-slop-cleaner pass and a full verification rerun are boundary duties and are optional here; when either is supplied it must pass and be blocker-free. A `deferredToBatch` gate must NOT contain `architectReview`, `executorQa`, or `validationBatchClose` — deferring never manufactures fake review approvals.
+- **Lane declaration is fail-closed.** `deferredToBatch.ranLanes` declares which lanes actually ran. A declared lane whose evidence is missing is rejected, evidence for an undeclared lane is rejected, `targetedVerification` must always be declared when `ranLanes` is present, and `ranLanes` can never declare `architectReview` or `executorQa`. Omitting `ranLanes` is allowed only for a gate that carries the mandatory targeted lane alone.
+- **The final member** (`finalGoalId`) checkpoints `complete` with the normal full strict gate PLUS a top-level `validationBatchClose` proof that covers all member IDs, member metadata hashes, member receipt/checkpoint-ledger-event IDs, per-member change-set hashes, and union change-set coverage. The final close only starts once every non-final member is already `complete` with a structurally fresh deferred receipt (out-of-order close is rejected).
+- Close state is append-only proof: it lives in the final member's checkpoint receipt and matching `goal_checkpointed` ledger row only. Never stamp `closedReceiptId`/`closedAt` or any close-state field onto member goals, and never append a separate close ledger event.
+- Change sets are cumulative-since-base: each member's `changeSet.paths` is the whole-worktree diff vs base (`cumulativeFromBase: true`), `memberGoalId` is a label not a per-path attribution, and `unionChangeSet.paths` carries no per-goal attribution.
+- Batch invalidation is fail-closed: steering mutations that would invalidate a batch are rejected while any member holds a fresh deferred receipt.

package/src/defaults/gjc-defaults.ts

@@ -9,10 +9,10 @@ import deepInterviewSkill from "./gjc/skills/deep-interview/SKILL.md" with { typ
 import ralplanSkill from "./gjc/skills/ralplan/SKILL.md" with { type: "text" };
 import teamSkill from "./gjc/skills/team/SKILL.md" with { type: "text" };
 import aiSlopCleanerFragment from "./gjc/skills/ultragoal/ai-slop-cleaner.md" with { type: "text" };
-import pipelineValidationContractsFragment from "./gjc/skills/ultragoal/pipeline-validation-contracts.md" with {
+import ultragoalSkill from "./gjc/skills/ultragoal/SKILL.md" with { type: "text" };
+import validationBatchContractsFragment from "./gjc/skills/ultragoal/validation-batch-contracts.md" with {
 	type: "text",
 };
-import ultragoalSkill from "./gjc/skills/ultragoal/SKILL.md" with { type: "text" };
 
 export const DEFAULT_GJC_DEFINITION_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"] as const;
 export type DefaultGjcDefinitionName = (typeof DEFAULT_GJC_DEFINITION_NAMES)[number];
@@ -119,8 +119,8 @@ const DEFAULT_GJC_DEFINITIONS: readonly DefaultGjcDefinition[] = [
 	{
 		kind: "skill-fragment",
 		parentSkillName: "ultragoal",
-		relativePath: "skill-fragments/ultragoal/pipeline-validation-contracts.md",
-		content: pipelineValidationContractsFragment,
+		relativePath: "skill-fragments/ultragoal/validation-batch-contracts.md",
+		content: validationBatchContractsFragment,
 	},
 ];
 

package/src/exa/mcp-client.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "@gajae-code/ai";
-import { $env, logger } from "@gajae-code/utils";
+import { $credentialEnv, logger } from "@gajae-code/utils";
 import type { CustomTool, CustomToolResult } from "../extensibility/custom-tools/types";
 import { callMCP } from "../runtime-mcp/json-rpc";
 import type {
@@ -11,9 +11,18 @@ import type {
 	MCPToolWrapperConfig,
 } from "./types";
 
-/** Find EXA_API_KEY from Bun.env or .env files */
+/**
+ * Find `EXA_API_KEY` from trusted environment sources.
+ *
+ * The key authenticates every Exa MCP call and travels in the request URL, so
+ * whatever can set it decides which account the agent's searches run through —
+ * and therefore who can see those queries. `$env` merges the caller's `cwd/.env`
+ * into `process.env`, so reading it there would let repository content supply
+ * that account. Resolve it the same way provider credentials are: launching
+ * shell plus GJC/user-owned `.env` files, never the project `.env`.
+ */
 export function findApiKey(): string | null {
-	return $env.EXA_API_KEY;
+	return $credentialEnv("EXA_API_KEY") ?? null;
 }
 
 function asRecord(value: unknown): Record<string, unknown> | null {

package/src/exec/bash-executor.ts

@@ -8,12 +8,125 @@ import { executeShell, type MinimizerOptions, Shell } from "@gajae-code/natives"
 import { postmortem } from "@gajae-code/utils";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
-import { OutputSink } from "../session/streaming-output";
-import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
+import {
+	DEFAULT_ARTIFACT_MAX_BYTES,
+	DEFAULT_MAX_BYTES,
+	OutputSink,
+	type TerminalArtifactPublisher,
+	truncateHeadBytes,
+} from "../session/streaming-output";
+import { formatArtifactReference, resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
 import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
+export interface BashArtifactSaveSummary {
+	artifactId: string;
+	complete: boolean;
+	omittedBytes?: number;
+}
+
+export type BashMinimizedSaveReturn = BashArtifactSaveResult | BashArtifactSaveSummary | string | undefined;
+
+export type BashArtifactSaveResult =
+	| { status: "saved"; artifactId: string; complete: true; omittedBytes?: undefined }
+	| { status: "saved"; artifactId: string; complete: false; omittedBytes: number }
+	| { status: "unavailable" }
+	| { status: "failed"; diagnostic: string };
+
+function summarizeLegacyArtifactSave(artifactId: string, originalText: string): BashArtifactSaveResult {
+	const inputBytes = Buffer.byteLength(originalText, "utf-8");
+	if (inputBytes <= DEFAULT_ARTIFACT_MAX_BYTES) {
+		return { status: "saved", artifactId, complete: true };
+	}
+	const retainedBytes = truncateHeadBytes(originalText, DEFAULT_ARTIFACT_MAX_BYTES).bytes;
+	return {
+		status: "saved",
+		artifactId,
+		complete: false,
+		omittedBytes: inputBytes - retainedBytes,
+	};
+}
+
+function normalizeExplicitSavedArtifact(
+	artifactId: string,
+	complete: boolean,
+	omittedBytes: number | undefined,
+): BashArtifactSaveResult {
+	if (complete) {
+		return (omittedBytes ?? 0) > 0
+			? { status: "failed", diagnostic: "artifact save reported complete output with omitted bytes" }
+			: { status: "saved", artifactId, complete: true };
+	}
+	return typeof omittedBytes === "number" && omittedBytes > 0
+		? { status: "saved", artifactId, complete: false, omittedBytes }
+		: { status: "failed", diagnostic: "artifact save reported incomplete output without omitted bytes" };
+}
+
+function normalizeMinimizedSaveResult(value: BashMinimizedSaveReturn, originalText: string): BashArtifactSaveResult {
+	if (typeof value === "string") return summarizeLegacyArtifactSave(value, originalText);
+	if (!value) return { status: "unavailable" };
+	if (!("status" in value)) {
+		return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
+	}
+	if (value.status !== "saved") return value;
+	return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
+}
+
+export function normalizeMinimizedSaveResultForTests(
+	value: BashMinimizedSaveReturn,
+	originalText: string,
+): BashArtifactSaveResult {
+	return normalizeMinimizedSaveResult(value, originalText);
+}
+
+function completeRawArtifactAvailable(summary: {
+	artifactId?: string;
+	artifactTruncatedBytes?: number;
+	artifactFailureDiagnostic?: string;
+}): boolean {
+	return (
+		summary.artifactId !== undefined &&
+		(summary.artifactTruncatedBytes ?? 0) <= 0 &&
+		summary.artifactFailureDiagnostic === undefined
+	);
+}
+
+function appendModelNotice(output: string, notice: string): string {
+	const separator = output.length > 0 && !output.endsWith("\n") ? "\n" : "";
+	return `${output}${separator}${notice}\n`;
+}
+
+function minimizedSaveNotice(
+	result: BashArtifactSaveResult,
+	summary: { artifactId?: string; artifactTruncatedBytes?: number; artifactFailureDiagnostic?: string },
+): string | undefined {
+	if (result.status === "failed") return `Bash output artifact save failed: ${result.diagnostic}`;
+	if (result.status === "unavailable" && !completeRawArtifactAvailable(summary)) {
+		return "Bash output artifact unavailable: full original output could not be stored because artifact storage is unavailable.";
+	}
+	return undefined;
+}
+
+function minimizedArtifactFooter(result: Extract<BashArtifactSaveResult, { status: "saved" }>): string {
+	const reference = result.complete
+		? `artifact://${result.artifactId}`
+		: formatArtifactReference(result.artifactId, result.omittedBytes);
+	return `[raw output: ${reference}]`;
+}
+
 export interface BashExecutorOptions {
+	/**
+	 * Invoked when the native minimizer rewrote the command's output, giving
+	 * the caller a chance to persist the lossless original capture (typically
+	 * via the session's `ArtifactManager`). Complete saves preserve the
+	 * historical `[raw output: artifact://<id>]` footer; capped saves carry an
+	 * honest retained/omitted reference. A legacy string id is still accepted
+	 * for non-tool callers and is classified from the original UTF-8 byte count.
+	 */
+	onMinimizedSave?: (
+		originalText: string,
+		info: { filter: string; inputBytes: number; outputBytes: number },
+	) => Promise<BashMinimizedSaveReturn>;
 	cwd?: string;
 	timeout?: number | null;
 	onChunk?: (chunk: string) => void;
@@ -32,23 +145,18 @@ export interface BashExecutorOptions {
 	/** Artifact path/id for full output storage */
 	artifactPath?: string;
 	artifactId?: string;
+	/** Optional terminal publisher for managed artifacts without writable paths. */
+	artifactPublisher?: TerminalArtifactPublisher;
+	/** Optional Bash-specific retained tail budget in bytes. */
+	spillThreshold?: number;
+	/** Optional Bash-specific retained head budget in bytes. */
+	headBytes?: number;
 	/** Execute without retaining a native Shell in the persistent session registry. */
 	oneShot?: boolean;
 	/** Ignore user-configured shell command prefixes. Used by constrained read-only shells. */
 	ignoreShellPrefix?: boolean;
 	/** Skip sourced shell snapshots. Used by constrained read-only shells. */
 	disableShellSnapshot?: boolean;
-	/**
-	 * Invoked when the native minimizer rewrote the command's output, giving
-	 * the caller a chance to persist the lossless original capture (typically
-	 * via the session's `ArtifactManager`). The returned id is spliced into
-	 * the sink output as `artifact://<id>` so the agent can retrieve the raw
-	 * bytes. Return `undefined` to skip the footer.
-	 */
-	onMinimizedSave?: (
-		originalText: string,
-		info: { filter: string; inputBytes: number; outputBytes: number },
-	) => Promise<string | undefined>;
 }
 
 export interface BashResult {
@@ -61,6 +169,8 @@ export interface BashResult {
 	outputLines: number;
 	outputBytes: number;
 	artifactId?: string;
+	artifactTruncatedBytes?: number;
+	artifactFailureDiagnostic?: string;
 }
 
 const shellSessions = new Map<string, Shell>();
@@ -144,7 +254,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		onRawChunk: options?.onRawChunk,
 		artifactPath: options?.artifactPath,
 		artifactId: options?.artifactId,
-		headBytes: resolveOutputSinkHeadBytes(settings),
+		artifactPublisher: options?.artifactPublisher,
+		spillThreshold: options?.spillThreshold ?? DEFAULT_MAX_BYTES,
+		headBytes: options?.headBytes ?? resolveOutputSinkHeadBytes(settings),
 		maxColumns: resolveOutputMaxColumns(settings),
 		// Throttle the streaming preview callback to avoid saturating the
 		// event loop when commands produce massive output (e.g. seq 1 50M).
@@ -332,21 +444,23 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 
 		// When the native minimizer rewrote the output, swap the sink's accumulated
 		// raw stream for the minimized text, persist the original as a session
-		// artifact, and splice an `artifact://<id>` footer into the visible text so
-		// the agent can retrieve the raw bytes losslessly.
+		// artifact, and splice an artifact footer into the visible text so the agent
+		// can retrieve retained raw bytes without a false completeness claim.
 		const minimized = winner.result.minimized;
+		let minimizedSaveResult: BashArtifactSaveResult | undefined;
 		if (minimized && minimized.text !== minimized.originalText) {
 			sink.replace(minimized.text);
-			if (options?.onMinimizedSave) {
-				const artifactId = await options.onMinimizedSave(minimized.originalText, {
-					filter: minimized.filter,
-					inputBytes: minimized.inputBytes,
-					outputBytes: minimized.outputBytes,
-				});
-				if (artifactId) {
-					const sep = minimized.text.endsWith("\n") ? "" : "\n";
-					sink.push(`${sep}[raw output: artifact://${artifactId}]\n`);
-				}
+			const saved = options?.onMinimizedSave
+				? await options.onMinimizedSave(minimized.originalText, {
+						filter: minimized.filter,
+						inputBytes: minimized.inputBytes,
+						outputBytes: minimized.outputBytes,
+					})
+				: undefined;
+			minimizedSaveResult = normalizeMinimizedSaveResult(saved, minimized.originalText);
+			if (minimizedSaveResult.status === "saved") {
+				const sep = minimized.text.endsWith("\n") ? "" : "\n";
+				sink.push(`${sep}${minimizedArtifactFooter(minimizedSaveResult)}\n`);
 			}
 		}
 
@@ -366,10 +480,13 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		}
 
 		// Normal completion
+		const summary = await sink.dump();
+		const saveNotice = minimizedSaveResult ? minimizedSaveNotice(minimizedSaveResult, summary) : undefined;
 		return {
 			exitCode: winner.result.exitCode,
 			cancelled: false,
-			...(await sink.dump()),
+			...summary,
+			...(saveNotice ? { output: appendModelNotice(summary.output, saveNotice) } : {}),
 		};
 	} catch (err) {
 		resetSession = true;

package/src/extensibility/extensions/runner.ts

@@ -179,8 +179,12 @@ export class ExtensionRunner {
 
 	#getModel: () => Model | undefined = () => undefined;
 	#isIdleFn: () => boolean = () => true;
+	#getActivePromptHandleFn: () => string | undefined = () => undefined;
 	#waitForIdleFn: () => Promise<void> = async () => {};
 	#abortFn: () => void = () => {};
+	#abortPromptAndWaitFn: NonNullable<ExtensionContextActions["abortPromptAndWait"]> = async () => {
+		throw new Error("abortPromptAndWait binding is unavailable");
+	};
 	#hasPendingMessagesFn: () => boolean = () => false;
 	#getPendingMessageCountsFn: () => { steering: number; followUp: number; nextTurn: number } = () => ({
 		steering: 0,
@@ -214,6 +218,7 @@ export class ExtensionRunner {
 	#getJobsFn: ExtensionContextActions["getJobs"] = undefined;
 	#sdkControlFn: ExtensionContextActions["sdkControl"] = undefined;
 	#setSdkPermissionProviderFn: ExtensionContextActions["setSdkPermissionProvider"] = undefined;
+	#setSdkClientBridgeFn: ExtensionContextActions["setSdkClientBridge"] = undefined;
 
 	#invokeSkillFn: ExtensionContextActions["invokeSkill"] = undefined;
 	#setPlanModeFn: ExtensionContextActions["setPlanMode"] = undefined;
@@ -297,7 +302,13 @@ export class ExtensionRunner {
 		// Context actions (required)
 		this.#getModel = contextActions.getModel;
 		this.#isIdleFn = contextActions.isIdle;
+		this.#getActivePromptHandleFn = contextActions.getActivePromptHandle ?? (() => undefined);
 		this.#abortFn = contextActions.abort;
+		this.#abortPromptAndWaitFn =
+			contextActions.abortPromptAndWait ??
+			(async () => {
+				throw new Error("abortPromptAndWait binding is unavailable");
+			});
 		this.#hasPendingMessagesFn = contextActions.hasPendingMessages;
 		this.#getPendingMessageCountsFn =
 			contextActions.getPendingMessageCounts ?? (() => ({ steering: 0, followUp: 0, nextTurn: 0 }));
@@ -331,6 +342,7 @@ export class ExtensionRunner {
 		this.#getJobsFn = contextActions.getJobs;
 		this.#sdkControlFn = contextActions.sdkControl;
 		this.#setSdkPermissionProviderFn = contextActions.setSdkPermissionProvider;
+		this.#setSdkClientBridgeFn = contextActions.setSdkClientBridge;
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -551,8 +563,10 @@ export class ExtensionRunner {
 			get model() {
 				return getModel();
 			},
+			getActivePromptHandle: () => this.#getActivePromptHandleFn(),
 			isIdle: () => this.#isIdleFn(),
 			abort: () => this.#abortFn(),
+			abortPromptAndWait: (handle, options) => this.#abortPromptAndWaitFn(handle, options),
 			hasPendingMessages: () => this.#hasPendingMessagesFn(),
 			getPendingMessageCounts: () => this.#getPendingMessageCountsFn(),
 			getTranscript: () => this.#getTranscriptFn(),
@@ -582,6 +596,7 @@ export class ExtensionRunner {
 			getJobs: () => this.#getJobsFn?.(),
 			sdkControl: (operation, input) => this.#sdkControlFn?.(operation, input),
 			setSdkPermissionProvider: provider => this.#setSdkPermissionProviderFn?.(provider),
+			setSdkClientBridge: bridge => this.#setSdkClientBridgeFn?.(bridge),
 			sdkBindings: () => [
 				...(this.#cycleModelFn ? ["cycleModel"] : []),
 				...(this.#setModelProfileFn ? ["setModelProfile"] : []),

package/src/extensibility/extensions/types.ts

@@ -8,7 +8,13 @@
  * - Interact with the user via UI primitives
  */
 
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@gajae-code/agent-core";
+import type {
+	AgentMessage,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	RunSettlementProof,
+	ThinkingLevel,
+} from "@gajae-code/agent-core";
 import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type {
 	Api,
@@ -38,6 +44,7 @@ import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
 import type {
+	ClientBridge,
 	ClientBridgePermissionOption,
 	ClientBridgePermissionOutcome,
 	ClientBridgePermissionToolCall,
@@ -355,8 +362,12 @@ export interface ExtensionContext {
 	model: Model | undefined;
 	/** Whether the agent is idle (not streaming) */
 	isIdle(): boolean;
+	/** Stable resource ownership identifier for the active prompt run. */
+	getActivePromptHandle(): string | undefined;
 	/** Abort the current agent operation */
 	abort(): void;
+	/** Abort and prove whether resources for a specific prompt settled. */
+	abortPromptAndWait?(handle: string, options: { graceMs: number }): Promise<RunSettlementProof>;
 	/** Whether there are queued messages waiting */
 	hasPendingMessages(): boolean;
 	/** Typed pending-message counts per queue (steering, follow-up, next-turn). */
@@ -416,6 +427,8 @@ export interface ExtensionContext {
 			  ) => Promise<ClientBridgePermissionOutcome>)
 			| undefined,
 	): void;
+	/** Install a client bridge backed by a live SDK reverse provider lease. */
+	setSdkClientBridge?(bridge: ClientBridge | undefined): void;
 	/** Names of session SDK seams actually installed by the active runtime. */
 	sdkBindings?(): readonly string[];
 
@@ -1436,7 +1449,10 @@ export interface ExtensionActions {
 export interface ExtensionContextActions {
 	getModel: () => Model | undefined;
 	isIdle: () => boolean;
+	/** Stable resource ownership identifier for the active prompt run. */
+	getActivePromptHandle?: () => string | undefined;
 	abort: () => void;
+	abortPromptAndWait?: (handle: string, options: { graceMs: number }) => Promise<RunSettlementProof>;
 	hasPendingMessages: () => boolean;
 	/** Typed pending-message counts per queue; optional for embedders without a counted queue. */
 	getPendingMessageCounts?: () => { steering: number; followUp: number; nextTurn: number };
@@ -1484,6 +1500,7 @@ export interface ExtensionContextActions {
 			  ) => Promise<ClientBridgePermissionOutcome>)
 			| undefined,
 	) => void;
+	setSdkClientBridge?: (bridge: ClientBridge | undefined) => void;
 	sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
 	invokeSkill?: (
 		name: string,

package/src/extensibility/gjc-plugins/constrained-hooks.ts

@@ -1,8 +1,8 @@
 import { logger } from "@gajae-code/utils";
-
+import { bundleIdentity } from "./lifecycle-reconciliation";
 import { loadEffectiveGjcPluginRegistry } from "./registry";
 import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
-import { GjcPluginLoadError, type GjcPluginRegistryEntry } from "./types";
+import { GjcPluginLoadError, type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
 
 /**
  * Constrained plugin-hook loader.
@@ -37,6 +37,7 @@ const DENIED_API_METHODS = [
 
 interface DeclaredHook {
 	plugin: string;
+	scope: GjcPluginScope;
 	event: string;
 	target?: string;
 	phase?: "before" | "after";
@@ -52,6 +53,7 @@ function collectDeclaredHooks(entries: readonly GjcPluginRegistryEntry[]): Decla
 			if (disabled.has(h.extensionId)) continue;
 			out.push({
 				plugin: entry.name,
+				scope: entry.scope,
 				event: h.event,
 				target: h.target,
 				phase: h.phase,
@@ -88,6 +90,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}:${declared.target ?? ""}`,
 				code: "invalid_hook",
@@ -99,6 +102,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code: "invalid_hook",
@@ -113,6 +117,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code,
@@ -125,6 +130,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code: "runtime_mismatch",