@gajae-code/coding-agent 0.12.18 → 0.12.20

package/dist/types/session/session-storage.d.ts

@@ -16,6 +16,22 @@ export interface SessionStorageSnapshot {
     bytes: Uint8Array;
     stat: SessionStorageStat;
 }
+export interface SessionStorageExactReplacementExpectation {
+    readonly stat: SessionStorageStat;
+    readonly sha256: string;
+}
+/** Upper bound for one descriptor-validated recorded range read. */
+export declare const SESSION_RANGE_READ_MAX_BYTES: number;
+/**
+ * One bounded recorded-length read validated against a single opened descriptor.
+ * `bytes` is exactly `length` bytes from `[start, start + length)` of the same
+ * regular-file object; `stat` is the fresh post-read descriptor snapshot so the
+ * caller can compare dev/ino/nlink against the pathname before committing an index.
+ */
+export interface SessionStorageRangeSnapshot {
+    stat: SessionStorageStat;
+    bytes: Uint8Array;
+}
 /**
  * Four-state writer close lifecycle. Only a successful underlying close confirms
  * `closed`. A failure certified to have happened BEFORE the OS close was dispatched
@@ -93,6 +109,10 @@ export interface SessionStorageWriter {
     writeLineSync(line: string): void;
     flush(): Promise<void>;
     fsync(): Promise<void>;
+    /** Synchronously fsync all prior writes when the backend supports durable sidecar publication. */
+    fsyncSync?(): void;
+    /** Descriptor-bound identity captured from the still-open writer after fsync. */
+    statSync?(): SessionStorageStat;
     close(): Promise<void>;
     /**
      * Synchronously close the underlying descriptor. The certainty-aware close
@@ -107,6 +127,45 @@ export interface SessionStorageWriter {
     /** Stored error for non-success close states (`close_failed_retryable`/`close_unknown`). */
     getCloseError(): Error | undefined;
 }
+/** Upper bound for one staged line (excluding the trailing newline). */
+export declare const STAGED_WRITER_LINE_MAX_BYTES: number;
+/** Upper bound for aggregated different-length patches buffered for the publish-time overlay pass. */
+export declare const STAGED_WRITER_PATCH_LIMIT_BYTES: number;
+export declare const STAGED_WRITER_PATCH_MAX_COUNT = 65536;
+export declare const STAGED_MEMORY_WRITER_MAX_BYTES: number;
+export declare const STAGED_MEMORY_WRITER_MAX_LINES: number;
+/**
+ * Bounded staged streaming writer for one immutable one-shot destination (fork /
+ * capture). Lines are streamed to a sibling staging file; {@link publishNoReplace}
+ * atomically publishes the staged file only while the destination is still absent,
+ * so publication never materializes the whole file in memory. Different-length
+ * {@link patchLine} replacements are buffered (bounded) and applied by a second
+ * bounded streaming pass at publish time.
+ *
+ * `publishNoReplace` is reserved for immutable one-shot destinations and must never
+ * be used for the mutable `.spill.commit` marker (checked create/replace helpers
+ * exist for that path).
+ */
+export interface StagedStreamingWriter {
+    /** Append one complete line; the writer adds the trailing newline. */
+    writeLine(bytes: Uint8Array): void;
+    /** Move the line cursor to `ordinal` (0-based) so a later patchLine targets it. */
+    seekToLine(ordinal: number): void;
+    /**
+     * Replace the line at `ordinal` with `bytes`. Same-length replacements are
+     * applied in place; different-length replacements are buffered (bounded) and
+     * applied by the publish-time overlay pass.
+     */
+    patchLine(ordinal: number, bytes: Uint8Array): void;
+    /** Hand buffered writes to the kernel (the staged descriptor is unbuffered). */
+    flush(): void;
+    /** Synchronize the staged file. */
+    fsync(): void;
+    /** Close the staged descriptor; required before {@link publishNoReplace}. */
+    closeSync(): void;
+    /** Atomically publish the staged file at the destination only while it is absent. */
+    publishNoReplace(): void;
+}
 export interface SessionStorage {
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
@@ -134,6 +193,8 @@ export interface SessionStorage {
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     renameSync(path: string, nextPath: string): void;
+    /** Replace only while the destination still has the expected exact identity and bytes. */
+    replaceExactSync?(sourcePath: string, destinationPath: string, expected: SessionStorageExactReplacementExpectation): boolean;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
@@ -145,6 +206,12 @@ export interface SessionStorage {
      */
     deleteSessionVerified?(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
     openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+    /** Bounded recorded-length read with descriptor identity validation (additive). */
+    readRangeSync?(path: string, start: number, length: number): SessionStorageRangeSnapshot;
+    /** Async bounded recorded-length read with descriptor identity validation (additive). */
+    readRange?(path: string, start: number, length: number): Promise<SessionStorageRangeSnapshot>;
+    /** Open a staged streaming writer for one immutable one-shot destination (additive). */
+    openStagedWriter?(path: string, options?: SessionStorageWriterOpenOptions): StagedStreamingWriter;
 }
 /** Exact authorization evidence for a transcript or artifact path. */
 export interface SessionStorageFileIdentity {
@@ -277,6 +344,42 @@ export type NativeDirectoryTreeSnapshot = {
     rootIno: string;
     entries: NativeDirectoryTreeEntry[];
 };
+/** Physically observed commit-marker state; corrupt JSON is still `present`. */
+export type SessionCommitMarkerState = {
+    kind: "missing";
+} | {
+    kind: "present";
+    rawBytesSha256: string;
+    stat: SessionStorageStat;
+};
+/** Exact `present` expectation for one checked commit-marker replacement. */
+export interface SessionCommitMarkerPresentExpectation {
+    /** SHA-256 of the exact raw marker bytes physically on disk (corrupt JSON included). */
+    rawBytesSha256: string;
+    /** Descriptor snapshot of the marker object expected to be replaced. */
+    descriptorIdentity: SessionStorageStat;
+}
+/** Snapshot one commit marker's physical state without granting write authority. */
+export declare function readSessionCommitMarkerSync(storage: SessionStorage, markerPath: string): SessionCommitMarkerState;
+/**
+ * Checked commit-marker create: publishes only while the marker is still `missing`.
+ * Temp + fsync + atomic create-if-absent + directory fsync (file backend); the
+ * in-memory backend mirrors the same missing-expectation abort. Leftover temps are
+ * removed on any failure. Runs inside the caller's persistence fence.
+ */
+export declare function createSessionCommitMarkerCheckedSync(storage: SessionStorage, markerPath: string, bytes: Uint8Array, options?: {
+    securityContext?: SessionStorageSecurityContext;
+}): void;
+/**
+ * Checked commit-marker replace: replaces only on an exact `present` raw/hash +
+ * descriptor identity match (corrupt-present included). Temp + fsync + checked
+ * atomic rename + directory fsync (file backend); any mismatch aborts with the
+ * current marker untouched. The in-memory backend mirrors the same aborts. Runs
+ * inside the caller's persistence fence.
+ */
+export declare function replaceSessionCommitMarkerCheckedSync(storage: SessionStorage, markerPath: string, bytes: Uint8Array, expected: SessionCommitMarkerPresentExpectation, options?: {
+    securityContext?: SessionStorageSecurityContext;
+}): void;
 export declare class FileSessionStorage implements SessionStorage {
     #private;
     ensureDirSync(dir: string): void;
@@ -285,6 +388,15 @@ export declare class FileSessionStorage implements SessionStorage {
     readTextSync(fpath: string): string;
     readBytesSync(fpath: string): Uint8Array;
     readSnapshotSync(fpath: string): SessionStorageSnapshot;
+    /**
+     * Bounded recorded-length read with descriptor identity validation: opens one
+     * no-follow descriptor, verifies the requested range is fully present, reads
+     * exactly `length` bytes, and revalidates dev/ino/nlink on the same descriptor
+     * plus the pathname (append-only size growth is tolerated; an object swap is
+     * rejected). No path-based Bun Blob reads for managed authority.
+     */
+    readRangeSync(fpath: string, start: number, length: number): SessionStorageRangeSnapshot;
+    readRange(fpath: string, start: number, length: number): Promise<SessionStorageRangeSnapshot>;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     listFilesByMtime(dir: string, pattern: string): Promise<Array<{
@@ -298,9 +410,11 @@ export declare class FileSessionStorage implements SessionStorage {
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     renameSync(path: string, nextPath: string): void;
+    replaceExactSync(sourcePath: string, destinationPath: string, expected: SessionStorageExactReplacementExpectation): boolean;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+    openStagedWriter(path: string, options?: SessionStorageWriterOpenOptions): StagedStreamingWriter;
     /**
      * Delete a session and sibling artifacts in an operator-selected explicit directory.
      * Default managed roots use deleteSessionVerified and never call this path.
@@ -317,10 +431,18 @@ export declare class MemorySessionStorage implements SessionStorage {
     #private;
     ensureDirSync(_dir: string): void;
     existsSync(path: string): boolean;
+    writeBytesOwnedSync(path: string, content: Buffer): void;
     writeTextSync(path: string, content: string): void;
     readTextSync(path: string): string;
     readBytesSync(path: string): Uint8Array;
     readSnapshotSync(path: string): SessionStorageSnapshot;
+    /**
+     * Bounded recorded-length read with descriptor identity validation: mirrors the
+     * file backend's contract (dev/ino/nlink identity, exact `length` bytes present)
+     * against the in-memory file model so parity tests can compare backends.
+     */
+    readRangeSync(path: string, start: number, length: number): SessionStorageRangeSnapshot;
+    readRange(path: string, start: number, length: number): Promise<SessionStorageRangeSnapshot>;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     listFilesByMtime(dir: string, pattern: string): Promise<Array<{
@@ -334,10 +456,58 @@ export declare class MemorySessionStorage implements SessionStorage {
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     renameSync(path: string, nextPath: string): void;
+    replaceExactSync(sourcePath: string, destinationPath: string, expected: SessionStorageExactReplacementExpectation): boolean;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
     deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
     openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+    openStagedWriter(path: string): StagedStreamingWriter;
 }
+/**
+ * Outcome of a disk-retention retirement attempt.
+ *
+ * `kept` means the transcript survived and nothing of the session was
+ * destroyed, with the exact reason so `gjc gc --disk` can report it.
+ * `cleanup_pending` means the delete authority already detached or removed the
+ * session's artifact tree (or quarantined the transcript) before it stopped:
+ * the record survives, the session does not, and a caller must NOT report that
+ * as an ordinary keep.
+ */
+export type SessionRetirementOutcome = {
+    kind: "retired";
+} | {
+    kind: "kept";
+    reason: string;
+} | {
+    kind: "cleanup_pending";
+    reason: string;
+};
+/**
+ * Non-mutating projection of {@link retireSessionTranscript}: would the
+ * retention pass's own preconditions let this transcript be retired at all?
+ *
+ * `gjc gc --disk` runs it so a dry run reports the verdict a prune would reach
+ * instead of promising bytes the delete authority will refuse to release. The
+ * authority's verdict (containment, identity, artifact tree) is deliberately
+ * not predicted here — it is re-derived against live state at delete time.
+ */
+export declare function probeSessionRetirement(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string): {
+    kind: "retirable";
+} | {
+    kind: "kept";
+    reason: string;
+};
+/**
+ * Retire one managed session transcript through the verified hard-delete
+ * authority.
+ *
+ * This is the only supported way for a retention pass to remove a transcript:
+ * identity, containment, header id/cwd, artifact tree and parent directory are
+ * all re-verified inside {@link FileSessionStorage.deleteSessionVerified}, and
+ * anything ambiguous fails closed as `kept` rather than deleting bytes. The
+ * caller owns the retention policy; this function owns nothing but the delete
+ * authority.
+ */
+export declare function retireSessionTranscript(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string): Promise<SessionRetirementOutcome>;
 export {};

package/dist/types/task/executor.d.ts

@@ -16,6 +16,7 @@ import type { ForkContextSeed } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
 import { SessionManager } from "../session/session-manager";
+import "../tools/yield";
 import type { ContextFileEntry } from "../tools";
 import type { EventBus } from "../utils/event-bus";
 import type { WorkspaceTree } from "../workspace-tree";
@@ -112,7 +113,7 @@ export interface ExecutorOptions {
 export declare class ManagedTaskPersistence {
     #private;
     constructor(artifacts: ArtifactManager, taskId: string);
-    openSession(cwd: string): Promise<SessionManager>;
+    openSession(cwd: string, sessionMemoryMode?: "off" | "shadow" | "enabled"): Promise<SessionManager>;
     publishOutput(rawOutput: string, metadata: Uint8Array): Promise<void>;
 }
 export declare function createManagedTaskPersistence(artifacts: ArtifactManager, taskId: string): ManagedTaskPersistence;

package/dist/types/tools/bash.d.ts

@@ -118,6 +118,7 @@ export interface ShellRendererConfig<TArgs> {
     resolveCommand?: (args: TArgs | undefined) => string | undefined;
     resolveCwd?: (args: TArgs | undefined) => string | undefined;
     resolveEnv?: (args: TArgs | undefined) => Record<string, string> | undefined;
+    compactCommand?: boolean;
 }
 export declare function getBashEnvForDisplay(args: BashRenderArgs): Record<string, string> | undefined;
 export declare function formatBashCommand(args: BashRenderArgs): string;

package/dist/types/tui/output-block.d.ts

@@ -11,6 +11,12 @@ export interface OutputBlockOptions {
     width: number;
     applyBg?: boolean;
 }
+/**
+ * Return the width available to section content after the output block's
+ * visible left and right borders. Keep callers on the same layout contract as
+ * renderOutputBlock so width-aware projections are not wrapped a second time.
+ */
+export declare function getOutputBlockContentWidth(width: number, theme: Theme): number;
 export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
 /**
  * Cached wrapper around `renderOutputBlock`.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.12.18",
+	"version": "0.12.20",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -54,13 +54,13 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.12.18",
-		"@gajae-code/agent-core": "0.12.18",
-		"@gajae-code/ai": "0.12.18",
-		"@gajae-code/bridge-client": "0.12.18",
-		"@gajae-code/natives": "0.12.18",
-		"@gajae-code/tui": "0.12.18",
-		"@gajae-code/utils": "0.12.18",
+		"@gajae-code/stats": "0.12.20",
+		"@gajae-code/agent-core": "0.12.20",
+		"@gajae-code/ai": "0.12.20",
+		"@gajae-code/bridge-client": "0.12.20",
+		"@gajae-code/natives": "0.12.20",
+		"@gajae-code/tui": "0.12.20",
+		"@gajae-code/utils": "0.12.20",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/args.ts

@@ -80,6 +80,25 @@ function isStartupLoginCommandArg(args: readonly string[], index: number): boole
 	return argumentCount === 0 || (argumentCount === 1 && !args[index + 1].startsWith("-"));
 }
 
+function takeFlagValue(args: readonly string[], index: number, flag: string, allowDashPrefixed = false): string {
+	const value = args[index + 1];
+	if (!value || (!allowDashPrefixed && value.startsWith("-"))) {
+		throw new CliParseError(`${flag} requires a value`);
+	}
+	return value;
+}
+
+function takePromptValue(
+	args: readonly string[],
+	index: number,
+	flag: string,
+	allowInlineDashPrefixed: boolean,
+): string {
+	const value = args[index + 1];
+	const allowSeparatedDashPrefixed = value === "-" || value?.startsWith("- ") === true;
+	return takeFlagValue(args, index, flag, allowInlineDashPrefixed || allowSeparatedDashPrefixed);
+}
+
 export function parseArgs(args: string[]): Args {
 	const result: Args = {
 		messages: [],
@@ -89,6 +108,7 @@ export function parseArgs(args: string[]): Args {
 
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
+		let hasInlineValue = false;
 
 		if (isStartupLoginCommandArg(args, i)) {
 			result.authBootstrap = true;
@@ -106,6 +126,7 @@ export function parseArgs(args: string[]): Args {
 			const eqIdx = arg.indexOf("=");
 			const value = arg.slice(eqIdx + 1);
 			arg = arg.slice(0, eqIdx);
+			hasInlineValue = true;
 			// Insert the value so the existing "args[++i]" logic picks it up
 			args.splice(i + 1, 0, value);
 		}
@@ -116,8 +137,9 @@ export function parseArgs(args: string[]): Args {
 			result.version = true;
 		} else if (arg === "--allow-home") {
 			result.allowHome = true;
-		} else if (arg === "--mode" && i + 1 < args.length) {
-			const mode = args[++i];
+		} else if (arg === "--mode") {
+			const mode = takeFlagValue(args, i, "--mode");
+			i++;
 			if (mode === "text" || mode === "json" || mode === "acp") {
 				result.mode = mode;
 			} else {
@@ -137,34 +159,34 @@ export function parseArgs(args: string[]): Args {
 			} else {
 				result.resume = true;
 			}
-		} else if (arg === "--fork" && i + 1 < args.length) {
-			result.fork = args[++i];
-		} else if (arg === "--provider" && i + 1 < args.length) {
-			result.provider = args[++i];
-		} else if (arg === "--model" && i + 1 < args.length) {
-			result.model = args[++i];
-		} else if (arg === "--smol" && i + 1 < args.length) {
-			result.smol = args[++i];
-		} else if (arg === "--slow" && i + 1 < args.length) {
-			result.slow = args[++i];
-		} else if (arg === "--plan" && i + 1 < args.length) {
-			result.plan = args[++i];
-		} else if (arg === "--mpreset" && i + 1 < args.length) {
-			result.mpreset = args[++i];
+		} else if (arg === "--fork") {
+			result.fork = takeFlagValue(args, i++, "--fork");
+		} else if (arg === "--provider") {
+			result.provider = takeFlagValue(args, i++, "--provider");
+		} else if (arg === "--model") {
+			result.model = takeFlagValue(args, i++, "--model");
+		} else if (arg === "--smol") {
+			result.smol = takeFlagValue(args, i++, "--smol");
+		} else if (arg === "--slow") {
+			result.slow = takeFlagValue(args, i++, "--slow");
+		} else if (arg === "--plan") {
+			result.plan = takeFlagValue(args, i++, "--plan");
+		} else if (arg === "--mpreset") {
+			result.mpreset = takeFlagValue(args, i++, "--mpreset");
 		} else if (arg === "--default") {
 			result.default = true;
-		} else if (arg === "--api-key" && i + 1 < args.length) {
-			result.apiKey = args[++i];
+		} else if (arg === "--api-key") {
+			result.apiKey = takeFlagValue(args, i++, "--api-key");
 		} else if (arg === "--credential") {
 			const next = args[i + 1];
 			if (!next || next.startsWith("-")) {
 				throw new CliParseError("--credential requires <selector>");
 			}
 			result.credential = args[++i];
-		} else if (arg === "--system-prompt" && i + 1 < args.length) {
-			result.systemPrompt = args[++i];
-		} else if (arg === "--append-system-prompt" && i + 1 < args.length) {
-			result.appendSystemPrompt = args[++i];
+		} else if (arg === "--system-prompt") {
+			result.systemPrompt = takePromptValue(args, i++, "--system-prompt", hasInlineValue);
+		} else if (arg === "--append-system-prompt") {
+			result.appendSystemPrompt = takePromptValue(args, i++, "--append-system-prompt", hasInlineValue);
 		} else if (arg === "--clipboard-transport") {
 			const next = args[i + 1];
 			if (!next || next.startsWith("-")) {
@@ -196,14 +218,16 @@ export function parseArgs(args: string[]): Args {
 				throw new CliParseError("--mcp-config requires <absolute-path>");
 			}
 			result.mcpConfig = args[++i];
-		} else if (arg === "--provider-session-id" && i + 1 < args.length) {
-			result.providerSessionId = args[++i];
+		} else if (arg === "--provider-session-id") {
+			result.providerSessionId = takeFlagValue(args, i++, "--provider-session-id");
 		} else if (arg === "--no-session") {
 			result.noSession = true;
-		} else if (arg === "--session-dir" && i + 1 < args.length) {
-			result.sessionDir = args[++i];
-		} else if (arg === "--models" && i + 1 < args.length) {
-			result.models = args[++i].split(",").map(s => s.trim());
+		} else if (arg === "--session-dir") {
+			result.sessionDir = takeFlagValue(args, i++, "--session-dir");
+		} else if (arg === "--models") {
+			result.models = takeFlagValue(args, i++, "--models")
+				.split(",")
+				.map(s => s.trim());
 		} else if (arg === "--no-tools") {
 			result.noTools = true;
 		} else if (arg === "--no-lsp") {
@@ -212,8 +236,23 @@ export function parseArgs(args: string[]): Args {
 			result.noPty = true;
 		} else if (arg === "--tmux") {
 			result.tmux = true;
-		} else if (arg === "--tools" && i + 1 < args.length) {
-			const toolNames = args[++i]
+		} else if (arg === "--extension" || arg === "-e") {
+			const extension = takeFlagValue(args, i++, "--extension");
+			result.extensions = [...(result.extensions ?? []), extension];
+		} else if (arg === "--hook") {
+			const hook = takeFlagValue(args, i++, "--hook");
+			result.hooks = [...(result.hooks ?? []), hook];
+		} else if (arg === "--no-extensions") {
+			result.noExtensions = true;
+		} else if (arg === "--no-skills") {
+			result.noSkills = true;
+		} else if (arg === "--skills") {
+			result.skills = takeFlagValue(args, i++, "--skills")
+				.split(",")
+				.map(s => s.trim())
+				.filter(Boolean);
+		} else if (arg === "--tools") {
+			const toolNames = takeFlagValue(args, i++, "--tools")
 				.split(",")
 				.map(s => s.trim().toLowerCase())
 				.filter(Boolean);
@@ -248,8 +287,8 @@ export function parseArgs(args: string[]): Args {
 			result.thinking = thinking;
 		} else if (arg === "--print" || arg === "-p") {
 			result.print = true;
-		} else if (arg === "--export" && i + 1 < args.length) {
-			result.export = args[++i];
+		} else if (arg === "--export") {
+			result.export = takeFlagValue(args, i++, "--export");
 		} else if (arg === "--no-rules") {
 			result.noRules = true;
 		} else if (arg === "--no-title") {
@@ -263,13 +302,15 @@ export function parseArgs(args: string[]): Args {
 			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (!arg.startsWith("-")) {
+		} else if (arg.startsWith("-")) {
+			result.unknownFlags.set(arg, true);
+		} else {
 			result.messages.push(arg);
 		}
 	}
 
 	if (result.default && !result.mpreset) {
-		throw new Error("--default requires --mpreset <name>");
+		throw new CliParseError("--default requires --mpreset <name>");
 	}
 	if (
 		result.mcpConfig !== undefined &&

package/src/commands/acp.ts

@@ -4,7 +4,7 @@
  * Thin wrapper around the launch flow that forces `mode: "acp"` unless the
  * ACP terminal-auth flag asks the same command to open the interactive TUI.
  */
-import { Command } from "@gajae-code/utils/cli";
+import { CliParseError, Command } from "@gajae-code/utils/cli";
 import { parseArgs } from "../cli/args";
 import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
@@ -16,6 +16,12 @@ export default class Acp extends Command {
 	async run(): Promise<void> {
 		const { args, terminalAuth } = prepareAcpTerminalAuthArgs(this.argv);
 		const parsed = parseArgs(args);
+		if (parsed.unknownFlags.size > 0) {
+			throw new CliParseError(`Unknown ACP option: ${[...parsed.unknownFlags.keys()].join(", ")}`);
+		}
+		if (terminalAuth && parsed.mode !== undefined) {
+			throw new CliParseError("--acp-terminal-auth only supports --mode acp");
+		}
 		if (!terminalAuth) {
 			parsed.mode = "acp";
 		}

package/src/commands/gc.ts

@@ -1,5 +1,21 @@
 import { Command, Flags } from "@gajae-code/utils/cli";
-import { runGjcGcCommand } from "../gjc-runtime/gc-runtime";
+import { isSettingsInitialized, settings } from "../config/settings";
+import { type GcDiskPolicy, runGjcGcCommand } from "../gjc-runtime/gc-runtime";
+
+/**
+ * Resolve the `gc.*` retention knobs from settings. When settings are not
+ * initialized (headless/early invocation) the runtime falls back to its
+ * schema-backed defaults, so this returns nothing rather than guessing.
+ */
+function resolveDiskPolicyFromSettings(): Partial<GcDiskPolicy> | undefined {
+	if (!isSettingsInitialized()) return undefined;
+	return {
+		sessions_max_age_days: settings.get("gc.sessions.maxAgeDays"),
+		sessions_max_total_bytes: settings.get("gc.sessions.maxTotalBytes"),
+		natives_keep_versions: settings.get("gc.natives.keepVersions"),
+		backups_max_age_days: settings.get("gc.backups.maxAgeDays"),
+	};
+}
 
 export default class Gc extends Command {
 	static description = "Garbage-collect stale GJC session/PID records (dry-run by default)";
@@ -9,6 +25,10 @@ export default class Gc extends Command {
 		prune: Flags.boolean({ description: "Remove stale records (default: report only)", default: false }),
 		force: Flags.boolean({ description: "Alias for --prune (eligible records only)", default: false }),
 		"dry-run": Flags.boolean({ description: "Force report-only mode", default: false }),
+		disk: Flags.boolean({
+			description: "Also report on-disk retention (sessions, blobs, natives, backups)",
+			default: false,
+		}),
 		"repair-session-index": Flags.boolean({
 			description: "Quarantine a corrupt session-index suffix and retain its valid prefix",
 			default: false,
@@ -20,11 +40,20 @@ export default class Gc extends Command {
 		"gjc gc --json",
 		"gjc gc --prune",
 		"gjc gc --prune --json",
+		"gjc gc --disk",
+		"gjc gc --disk --json",
+		"gjc gc --disk --prune",
 		"gjc gc --repair-session-index --json",
 	];
 
 	async run(): Promise<void> {
-		const result = await runGjcGcCommand(this.argv, process.cwd(), process.env);
+		const result = await runGjcGcCommand(
+			this.argv,
+			process.cwd(),
+			process.env,
+			undefined,
+			resolveDiskPolicyFromSettings(),
+		);
 		if (result.stdout) process.stdout.write(result.stdout);
 		if (result.stderr) process.stderr.write(result.stderr);
 		process.exitCode = result.status;