@adhdev/daemon-core 0.9.54 → 0.9.56

package/dist/providers/contracts.d.ts

@@ -358,6 +358,8 @@ export interface ProviderModule {
     sendKey?: string;
     /** How the CLI adapter decides when to submit typed input */
     submitStrategy?: 'wait_for_echo' | 'immediate';
+    /** If true, typed input must echo on the PTY screen before the adapter sends Enter. */
+    requirePromptEchoBeforeSubmit?: boolean;
     /** Keep this provider out of the upstream auto-updated bundle */
     /** @deprecated Machine-level provider source policy now lives in config.providerSourceMode. Local overrides shadow upstream by root precedence and should not rely on provider-level disableUpstream. */
     disableUpstream?: boolean;

package/node_modules/@adhdev/session-host-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/session-host-core",
-  "version": "0.9.54",
+  "version": "0.9.56",
   "description": "ADHDev local session host core \u2014 session registry, protocol, buffers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.54",
+  "version": "0.9.56",
   "description": "ADHDev daemon core \u2014 CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/boot/daemon-lifecycle.ts

@@ -35,6 +35,7 @@ import {
 import { loadConfig } from '../config/config.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import type { IdeProviderInstance } from '../providers/ide-provider-instance.js';
+import { createDefaultGitCommandServices } from '../git/git-commands.js';
 
 // ─── Init Config ───
 
@@ -78,6 +79,9 @@ export interface DaemonInitConfig {
     statusInstanceId?: string;
     statusVersion?: string;
     statusDaemonMode?: boolean;
+
+    /** Fired before send_chat is dispatched — used for turn snapshot hooks */
+    onBeforeSendChat?: (params: { workspace: string; sessionId: string }) => void;
 }
 
 // ─── Result ───
@@ -256,6 +260,7 @@ export async function initDaemonComponents(config: DaemonInitConfig): Promise<Da
         providerLoader,
         instanceManager,
         sessionRegistry,
+        gitCommandServices: createDefaultGitCommandServices(),
         onProviderSettingChanged: async (providerType) => {
             await refreshProviderAvailability(providerType);
             config.onStatusChange?.();
@@ -264,6 +269,7 @@ export async function initDaemonComponents(config: DaemonInitConfig): Promise<Da
             await refreshProviderAvailability();
             config.onStatusChange?.();
         },
+        onBeforeSendChat: config.onBeforeSendChat,
     });
 
     // 8. AgentStreamManager

package/src/cli-adapters/provider-cli-adapter.ts

@@ -341,6 +341,12 @@ export class ProviderCliAdapter implements CliAdapter {
     private accumulatedRawBuffer: string = '';
     /** Current visible terminal screen snapshot */
     private terminalScreen = new TerminalScreen(24, 80);
+    private static readonly MAX_RESPONSE_BUFFER = 8000;
+    private static readonly MAX_RECENT_OUTPUT_BUFFER = 1000;
+    private responseBufferDroppedChars = 0;
+    private recentOutputDroppedChars = 0;
+    private accumulatedBufferDroppedChars = 0;
+    private accumulatedRawBufferDroppedChars = 0;
     /** Max accumulated buffer size. Sized to comfortably hold a single long
      *  Hermes turn (tool calls + reasoning + final bubble) without the
      *  rolling window pushing the turn's ╭─ opening line out of view. */
@@ -371,6 +377,27 @@ export class ProviderCliAdapter implements CliAdapter {
     private static readonly FINISH_RETRY_DELAY_MS = 300;
     private static readonly MAX_FINISH_RETRIES = 2;
 
+    private getBufferState(): NonNullable<CliSessionStatus['bufferState']> | undefined {
+        const build = (droppedChars: number, maxChars: number) => droppedChars > 0
+            ? { truncated: true, droppedChars, maxChars }
+            : undefined;
+        const responseBuffer = build(this.responseBufferDroppedChars, ProviderCliAdapter.MAX_RESPONSE_BUFFER);
+        const recentOutputBuffer = build(this.recentOutputDroppedChars, ProviderCliAdapter.MAX_RECENT_OUTPUT_BUFFER);
+        const accumulatedBuffer = build(this.accumulatedBufferDroppedChars, ProviderCliAdapter.MAX_ACCUMULATED_BUFFER);
+        const accumulatedRawBuffer = build(this.accumulatedRawBufferDroppedChars, ProviderCliAdapter.MAX_ACCUMULATED_BUFFER);
+        if (!responseBuffer && !recentOutputBuffer && !accumulatedBuffer && !accumulatedRawBuffer) return undefined;
+        return {
+            ...(responseBuffer ? { responseBuffer } : {}),
+            ...(recentOutputBuffer ? { recentOutputBuffer } : {}),
+            ...(accumulatedBuffer ? { accumulatedBuffer } : {}),
+            ...(accumulatedRawBuffer ? { accumulatedRawBuffer } : {}),
+        };
+    }
+
+    private recordBoundedAppendDrop(previousLength: number, appendedLength: number, nextLength: number): number {
+        return Math.max(0, (previousLength + appendedLength) - nextLength);
+    }
+
     private buildCommittedMessagesActivitySignature(): string {
         const last = this.committedMessages[this.committedMessages.length - 1];
         return [
@@ -598,6 +625,7 @@ export class ProviderCliAdapter implements CliAdapter {
     private readonly sendDelayMs: number;
     private readonly sendKey: string;
     private readonly submitStrategy: 'wait_for_echo' | 'immediate';
+    private readonly requirePromptEchoBeforeSubmit: boolean;
     private static readonly SCRIPT_STATUS_DEBOUNCE_MS = 3000;
 
     constructor(
@@ -620,6 +648,7 @@ export class ProviderCliAdapter implements CliAdapter {
         this.sendDelayMs = resolvedConfig.sendDelayMs;
         this.sendKey = resolvedConfig.sendKey;
         this.submitStrategy = resolvedConfig.submitStrategy;
+        this.requirePromptEchoBeforeSubmit = resolvedConfig.requirePromptEchoBeforeSubmit;
         this.providerResolutionMeta = resolvedConfig.providerResolutionMeta;
 
         // Scripts are required — loaded by ProviderLoader via compatibility array
@@ -845,7 +874,9 @@ export class ProviderCliAdapter implements CliAdapter {
         }
 
         if (this.isWaitingForResponse && cleanData) {
-            this.responseBuffer = appendBoundedText(this.responseBuffer, cleanData, 8000);
+            const previousResponseLen = this.responseBuffer.length;
+            this.responseBuffer = appendBoundedText(this.responseBuffer, cleanData, ProviderCliAdapter.MAX_RESPONSE_BUFFER);
+            this.responseBufferDroppedChars += this.recordBoundedAppendDrop(previousResponseLen, cleanData.length, this.responseBuffer.length);
         }
 
         // Server log forwarding
@@ -858,17 +889,22 @@ export class ProviderCliAdapter implements CliAdapter {
         }
 
         // Rolling buffers
+        const prevRecentLen = this.recentOutputBuffer.length;
         const prevAccumulatedLen = this.accumulatedBuffer.length;
         const prevAccumulatedRawLen = this.accumulatedRawBuffer.length;
-        this.recentOutputBuffer = appendBoundedText(this.recentOutputBuffer, cleanData, 1000);
+        this.recentOutputBuffer = appendBoundedText(this.recentOutputBuffer, cleanData, ProviderCliAdapter.MAX_RECENT_OUTPUT_BUFFER);
         this.accumulatedBuffer = appendBoundedText(this.accumulatedBuffer, cleanData, ProviderCliAdapter.MAX_ACCUMULATED_BUFFER);
         this.accumulatedRawBuffer = appendBoundedText(this.accumulatedRawBuffer, rawData, ProviderCliAdapter.MAX_ACCUMULATED_BUFFER);
+        const droppedRecent = this.recordBoundedAppendDrop(prevRecentLen, cleanData.length, this.recentOutputBuffer.length);
+        const droppedClean = this.recordBoundedAppendDrop(prevAccumulatedLen, cleanData.length, this.accumulatedBuffer.length);
+        const droppedRaw = this.recordBoundedAppendDrop(prevAccumulatedRawLen, rawData.length, this.accumulatedRawBuffer.length);
+        this.recentOutputDroppedChars += droppedRecent;
+        this.accumulatedBufferDroppedChars += droppedClean;
+        this.accumulatedRawBufferDroppedChars += droppedRaw;
         // Keep turn-scope offsets aligned with the truncated buffer so scoped
         // parses don't lose the beginning of a long turn (e.g. the Hermes
         // ╭─ opening line) when the rolling window sheds bytes.
         if (this.currentTurnScope) {
-            const droppedClean = (prevAccumulatedLen + cleanData.length) - this.accumulatedBuffer.length;
-            const droppedRaw = (prevAccumulatedRawLen + rawData.length) - this.accumulatedRawBuffer.length;
             if (droppedClean > 0) {
                 this.currentTurnScope.bufferStart = Math.max(0, this.currentTurnScope.bufferStart - droppedClean);
             }
@@ -1803,6 +1839,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 effectiveModal = parsedModal;
             }
         }
+        const bufferState = this.getBufferState();
         return {
             status: effectiveStatus,
             messages: [...this.committedMessages],
@@ -1810,6 +1847,7 @@ export class ProviderCliAdapter implements CliAdapter {
             activeModal: effectiveModal,
             errorMessage: this.parseErrorMessage || undefined,
             errorReason: this.parseErrorMessage ? 'parse_error' : undefined,
+            ...(bufferState ? { bufferState } : {}),
         };
     }
 
@@ -2054,10 +2092,12 @@ export class ProviderCliAdapter implements CliAdapter {
                 messages: hydratedMessages,
                 activeModal: parsed.activeModal ?? this.activeModal,
                 providerSessionId: typeof parsed.providerSessionId === 'string' ? parsed.providerSessionId : undefined,
+                ...(this.getBufferState() ? { bufferState: this.getBufferState() } : {}),
                 ...(this.providerOwnsTranscript() ? { transcriptAuthority: 'provider', coverage: this.shouldUseFullProviderTranscriptContext() ? 'full' : 'tail' } : {}),
             };
         } else {
             const messages = [...this.committedMessages];
+            const bufferState = this.getBufferState();
             result = {
                 id: 'cli_session',
                 status: this.currentStatus,
@@ -2071,6 +2111,7 @@ export class ProviderCliAdapter implements CliAdapter {
                         : message.timestamp,
                 })),
                 activeModal: this.activeModal,
+                ...(bufferState ? { bufferState } : {}),
             };
         }
 
@@ -2392,6 +2433,22 @@ export class ProviderCliAdapter implements CliAdapter {
         }
 
         if (elapsed >= state.maxEchoWaitMs) {
+            const diagnostic = {
+                elapsed,
+                maxEchoWaitMs: state.maxEchoWaitMs,
+                submitDelayMs: state.submitDelayMs,
+                promptSnippet: state.normalizedPromptSnippet,
+                requirePromptEchoBeforeSubmit: this.requirePromptEchoBeforeSubmit,
+                screenText: summarizeCliTraceText(screenText, 1000),
+            };
+            this.recordTrace('submit_echo_missing', diagnostic);
+            if (this.requirePromptEchoBeforeSubmit) {
+                const message = `${this.cliName} prompt echo was not observed on the PTY screen before submit`;
+                LOG.warn('CLI', `[${this.cliType}] ${message} elapsed=${elapsed}ms maxEchoWaitMs=${state.maxEchoWaitMs} screen=${JSON.stringify(diagnostic.screenText).slice(0, 240)}`);
+                completion.rejectOnce(new Error(message));
+                return;
+            }
+            LOG.warn('CLI', `[${this.cliType}] prompt echo was not observed before submit; sending submit key anyway elapsed=${elapsed}ms maxEchoWaitMs=${state.maxEchoWaitMs}`);
             this.submitSendKey(state, completion);
             return;
         }
@@ -2880,6 +2937,7 @@ export class ProviderCliAdapter implements CliAdapter {
             sendDelayMs: this.sendDelayMs,
             sendKey: this.sendKey,
             submitStrategy: this.submitStrategy,
+            requirePromptEchoBeforeSubmit: this.requirePromptEchoBeforeSubmit,
             submitPendingUntil: this.submitPendingUntil,
             responseSettleIgnoreUntil: this.responseSettleIgnoreUntil,
             resizeSuppressUntil: this.resizeSuppressUntil,

package/src/cli-adapters/provider-cli-config.d.ts

@@ -25,6 +25,7 @@ export interface ResolvedCliAdapterConfig {
     sendDelayMs: number;
     sendKey: string;
     submitStrategy: 'wait_for_echo' | 'immediate';
+    requirePromptEchoBeforeSubmit: boolean;
     providerResolutionMeta: ProviderResolutionMeta;
 }
 export declare function resolveCliAdapterConfig(provider: CliProviderModule): ResolvedCliAdapterConfig;

package/src/cli-adapters/provider-cli-config.ts

@@ -29,6 +29,7 @@ export interface ResolvedCliAdapterConfig {
     sendDelayMs: number;
     sendKey: string;
     submitStrategy: 'wait_for_echo' | 'immediate';
+    requirePromptEchoBeforeSubmit: boolean;
     providerResolutionMeta: ProviderResolutionMeta;
 }
 
@@ -55,6 +56,7 @@ export function resolveCliAdapterConfig(provider: CliProviderModule): ResolvedCl
             ? provider.sendKey
             : '\r',
         submitStrategy: provider.submitStrategy === 'immediate' ? 'immediate' : 'wait_for_echo',
+        requirePromptEchoBeforeSubmit: provider.requirePromptEchoBeforeSubmit === true,
         providerResolutionMeta: {
             type: provider.type,
             name: provider.name,

package/src/cli-adapters/provider-cli-shared.d.ts

@@ -104,6 +104,8 @@ export interface CliProviderModule {
     sendDelayMs?: number;
     sendKey?: string;
     submitStrategy?: 'wait_for_echo' | 'immediate';
+    /** Require the typed prompt to be visible on the PTY screen before sending Enter. */
+    requirePromptEchoBeforeSubmit?: boolean;
     /** Allow sending another prompt while the CLI is still generating so users can intervene mid-turn. */
     allowInputDuringGeneration?: boolean;
     scripts?: CliScripts;

package/src/cli-adapters/provider-cli-shared.ts

@@ -24,6 +24,12 @@ export interface CliSessionStatus {
     activeModal: { message: string; buttons: string[] } | null;
     errorMessage?: string;
     errorReason?: string;
+    bufferState?: {
+        responseBuffer?: { truncated: boolean; droppedChars: number; maxChars: number };
+        recentOutputBuffer?: { truncated: boolean; droppedChars: number; maxChars: number };
+        accumulatedBuffer?: { truncated: boolean; droppedChars: number; maxChars: number };
+        accumulatedRawBuffer?: { truncated: boolean; droppedChars: number; maxChars: number };
+    };
 }
 
 export interface ParsedSession {
@@ -122,6 +128,8 @@ export interface CliProviderModule {
     sendDelayMs?: number;
     sendKey?: string;
     submitStrategy?: 'wait_for_echo' | 'immediate';
+    /** Require the typed prompt to be visible on the PTY screen before sending Enter. */
+    requirePromptEchoBeforeSubmit?: boolean;
     /** Allow sending another prompt while the CLI is still generating so users can intervene mid-turn. */
     allowInputDuringGeneration?: boolean;
     /** When provider-owned, daemon treats provider parser output as canonical transcript authority. */

package/src/commands/handler.ts

@@ -50,6 +50,8 @@ export interface CommandContext {
     onProviderSettingChanged?: (providerType: string, key: string, value: any) => Promise<void> | void;
     onProviderSourceConfigChanged?: () => Promise<void> | void;
     gitCommandServices?: GitCommandServices;
+    /** Fired synchronously before send_chat is dispatched; fire-and-forget for callers */
+    onBeforeSendChat?: (params: { workspace: string; sessionId: string }) => void;
 }
 
 /**
@@ -424,6 +426,20 @@ export class DaemonCommandHandler implements CommandHelpers {
             }
         }
 
+        if (cmd === 'send_chat' && this._ctx.onBeforeSendChat) {
+            const sessionId = this._currentRoute.session?.sessionId;
+            const workspace = sessionId
+                ? (this._ctx.instanceManager?.getInstance(sessionId) as any)?.getState?.()?.workspace
+                : undefined;
+            if (workspace && sessionId) {
+                try {
+                    this._ctx.onBeforeSendChat({ workspace, sessionId });
+                } catch {
+                    // hook must not block send_chat
+                }
+            }
+        }
+
         try {
             result = await this.dispatch(cmd, args);
             this.logCommandEnd(cmd, result, startedAt);

package/src/git/git-commands.ts

@@ -41,6 +41,18 @@ export interface GitLogResult extends GitRepoIdentity {
   lastCheckedAt: number;
 }
 
+export interface GitCheckpointResult extends GitRepoIdentity {
+  commit: string;
+  message: string;
+  lastCheckedAt: number;
+}
+
+export interface GitStashPushResult extends GitRepoIdentity {
+  stashRef: string;
+  message: string;
+  lastCheckedAt: number;
+}
+
 export interface GitCommandServices {
   getStatus?: (params: { workspace: string }) => Promise<GitRepoStatus> | GitRepoStatus;
   getDiffSummary?: (params: { workspace: string; staged?: boolean }) => Promise<GitDiffSummary> | GitDiffSummary;
@@ -63,6 +75,19 @@ export interface GitCommandServices {
     since?: string;
     until?: string;
   }) => Promise<GitLogResult> | GitLogResult;
+  checkpoint?: (params: {
+    workspace: string;
+    message: string;
+    includeUntracked?: boolean;
+  }) => Promise<GitCheckpointResult> | GitCheckpointResult;
+  stashPush?: (params: {
+    workspace: string;
+    message: string;
+    includeUntracked?: boolean;
+  }) => Promise<GitStashPushResult> | GitStashPushResult;
+  stashPop?: (params: { workspace: string; stashRef?: string }) => Promise<void>;
+  checkoutFiles?: (params: { workspace: string; paths: string[] }) => Promise<{ checkedOut: string[] }>;
+  getRemoteUrl?: (params: { workspace: string; remote?: string }) => Promise<{ remoteUrl: string; remote: string }>;
 }
 
 type GitCommandFailure = {
@@ -77,7 +102,12 @@ type GitCommandSuccess =
   | { success: true; diff: GitFileDiff }
   | { success: true; snapshot: GitSnapshot }
   | { success: true; compare: GitSnapshotCompareSummary }
-  | { success: true; log: GitLogResult };
+  | { success: true; log: GitLogResult }
+  | { success: true; checkpoint: GitCheckpointResult }
+  | { success: true; stash: GitStashPushResult }
+  | { success: true; stashPopped: true }
+  | { success: true; checkedOut: string[] }
+  | { success: true; remoteUrl: string; remote: string };
 
 export type GitCommandResult = GitCommandSuccess | GitCommandFailure;
 
@@ -92,13 +122,7 @@ const GIT_COMMAND_NAMES = new Set<GitCommandName>([
   'git_stash_push',
   'git_stash_pop',
   'git_checkout_files',
-]);
-
-const MUTATING_COMMAND_NAMES = new Set<GitCommandName>([
-  'git_checkpoint',
-  'git_stash_push',
-  'git_stash_pop',
-  'git_checkout_files',
+  'git_remote_url',
 ]);
 
 const SNAPSHOT_REASONS = new Set<GitSnapshotReason>([
@@ -146,6 +170,11 @@ export function createDefaultGitCommandServices(): GitCommandServices {
     }),
     compareSnapshots: ({ beforeSnapshotId, afterSnapshotId }) => defaultSnapshotStore.compare(beforeSnapshotId, afterSnapshotId),
     getLog: ({ workspace, limit, path: filePath, since, until }) => getGitLog(workspace, { limit, path: filePath, since, until }),
+    checkpoint: async ({ workspace, message, includeUntracked = false }) => gitCheckpoint(workspace, message, includeUntracked),
+    stashPush: async ({ workspace, message, includeUntracked = false }) => gitStashPush(workspace, message, includeUntracked),
+    stashPop: async ({ workspace, stashRef }) => gitStashPop(workspace, stashRef),
+    checkoutFiles: async ({ workspace, paths }) => gitCheckoutFiles(workspace, paths),
+    getRemoteUrl: async ({ workspace, remote = 'origin' }) => gitGetRemoteUrl(workspace, remote),
   };
 }
 
@@ -240,10 +269,6 @@ export async function handleGitCommand(
     return failure('invalid_args', `Unknown Git command: ${command}`);
   }
 
-  if (MUTATING_COMMAND_NAMES.has(command)) {
-    return failure('invalid_args', `${command} is not implemented in daemon-core read-only Git routing`);
-  }
-
   const workspaceResult = validateWorkspace(args);
   if ('success' in workspaceResult) return workspaceResult;
   const { workspace } = workspaceResult;
@@ -310,11 +335,183 @@ export async function handleGitCommand(
       return 'success' in log ? log : { success: true, log };
     }
 
+    case 'git_checkpoint': {
+      if (!services.checkpoint) return serviceNotImplemented(command);
+      const msg = validateMutatingMessage(args?.message);
+      if (typeof msg !== 'string') return msg;
+      const includeUntracked = Boolean(args?.includeUntracked);
+      const checkpoint = await runService(() => services.checkpoint!({ workspace, message: msg, includeUntracked }));
+      return 'success' in checkpoint ? checkpoint : { success: true, checkpoint };
+    }
+
+    case 'git_stash_push': {
+      if (!services.stashPush) return serviceNotImplemented(command);
+      const msg = validateMutatingMessage(args?.message);
+      if (typeof msg !== 'string') return msg;
+      const includeUntracked = Boolean(args?.includeUntracked);
+      const stash = await runService(() => services.stashPush!({ workspace, message: msg, includeUntracked }));
+      return 'success' in stash ? stash : { success: true, stash };
+    }
+
+    case 'git_stash_pop': {
+      if (!services.stashPop) return serviceNotImplemented(command);
+      const stashRef = optionalString(args?.stashRef);
+      if (stashRef !== undefined && !/^stash@\{\d+\}$/.test(stashRef)) {
+        return failure('invalid_args', 'stashRef must match stash@{N} format');
+      }
+      const popResult = await runService(() => services.stashPop!({ workspace, stashRef }));
+      if (popResult !== undefined && 'success' in (popResult as object)) return popResult as GitCommandFailure;
+      return { success: true, stashPopped: true };
+    }
+
+    case 'git_checkout_files': {
+      if (!services.checkoutFiles) return serviceNotImplemented(command);
+      const paths = args?.paths;
+      if (!Array.isArray(paths) || paths.length === 0) {
+        return failure('invalid_args', 'paths must be a non-empty array');
+      }
+      if (paths.length > 50) {
+        return failure('invalid_args', 'paths array exceeds maximum of 50 entries');
+      }
+      const checkoutResult = await runService(() => services.checkoutFiles!({ workspace, paths }));
+      return 'success' in checkoutResult ? checkoutResult : { success: true, checkedOut: (checkoutResult as { checkedOut: string[] }).checkedOut };
+    }
+
+    case 'git_remote_url': {
+      if (!services.getRemoteUrl) return serviceNotImplemented(command);
+      const remote = typeof args?.remote === 'string' && args.remote.trim() ? args.remote.trim() : 'origin';
+      const remoteResult = await runService(() => services.getRemoteUrl!({ workspace, remote }));
+      if ('success' in remoteResult) return remoteResult;
+      return { success: true, remoteUrl: remoteResult.remoteUrl, remote: remoteResult.remote };
+    }
+
     default:
       return failure('invalid_args', `Unknown Git command: ${command}`);
   }
 }
 
+function validateMutatingMessage(value: unknown): string | GitCommandFailure {
+  if (typeof value !== 'string' || !value.trim()) {
+    return failure('invalid_args', 'message must be a non-empty string');
+  }
+  const msg = value.trim();
+  if (msg.length > 200) {
+    return failure('invalid_args', 'message must be 200 characters or fewer');
+  }
+  return msg;
+}
+
+async function gitCheckpoint(
+  workspace: string,
+  message: string,
+  includeUntracked: boolean,
+): Promise<GitCheckpointResult> {
+  const repo = await resolveGitRepository(workspace);
+  const repoRoot = repo.repoRoot!;
+
+  const statusResult = await getGitRepoStatus(workspace);
+  if (statusResult.hasConflicts) {
+    throw new GitCommandError('conflict', 'Repository has conflicts — resolve before checkpointing');
+  }
+
+  const addArgs = includeUntracked ? ['-A'] : ['-u'];
+  await runGit(repo, ['add', ...addArgs], { cwd: repoRoot });
+
+  const fullMsg = `adhdev: checkpoint ${message}`;
+  let commitSha: string;
+  try {
+    await runGit(repo, ['commit', '-m', fullMsg], { cwd: repoRoot });
+    const revResult = await runGit(repo, ['rev-parse', 'HEAD'], { cwd: repoRoot });
+    commitSha = revResult.stdout.trim();
+  } catch (err: any) {
+    const output = (err?.stdout || '') + (err?.stderr || '');
+    if (/nothing to commit/i.test(output)) {
+      throw new GitCommandError('git_command_failed', 'Nothing to commit');
+    }
+    throw err;
+  }
+
+  return {
+    workspace: repo.workspace,
+    repoRoot,
+    isGitRepo: true,
+    commit: commitSha,
+    message: fullMsg,
+    lastCheckedAt: Date.now(),
+  };
+}
+
+async function gitStashPush(
+  workspace: string,
+  message: string,
+  includeUntracked: boolean,
+): Promise<GitStashPushResult> {
+  const repo = await resolveGitRepository(workspace);
+  const repoRoot = repo.repoRoot!;
+
+  const stashArgs = ['stash', 'push', '-m', message];
+  if (includeUntracked) stashArgs.push('--include-untracked');
+
+  const result = await runGit(repo, stashArgs, { cwd: repoRoot });
+  if (/No local changes to save/i.test(result.stdout + result.stderr)) {
+    throw new GitCommandError('git_command_failed', 'Nothing to stash');
+  }
+
+  return {
+    workspace: repo.workspace,
+    repoRoot,
+    isGitRepo: true,
+    stashRef: 'stash@{0}',
+    message,
+    lastCheckedAt: Date.now(),
+  };
+}
+
+async function gitStashPop(workspace: string, stashRef?: string): Promise<void> {
+  const repo = await resolveGitRepository(workspace);
+  const repoRoot = repo.repoRoot!;
+
+  const popArgs = stashRef ? ['stash', 'pop', stashRef] : ['stash', 'pop'];
+  await runGit(repo, popArgs, { cwd: repoRoot });
+}
+
+async function gitCheckoutFiles(workspace: string, paths: string[]): Promise<{ checkedOut: string[] }> {
+  const repo = await resolveGitRepository(workspace);
+  const repoRoot = repo.repoRoot!;
+
+  const normalizedPaths: string[] = [];
+  for (const p of paths) {
+    if (typeof p !== 'string' || !p.trim() || p.includes('\0')) {
+      throw new GitCommandError('invalid_args', `Invalid path: ${String(p)}`);
+    }
+    if (path.isAbsolute(p)) {
+      throw new GitCommandError('invalid_args', `Path must be repository-relative, not absolute: ${p}`);
+    }
+    const normalized = path.normalize(p.trim()).split(path.sep).join('/');
+    if (normalized.startsWith('../') || normalized === '..') {
+      throw new GitCommandError('path_outside_repo', `Path is outside repository root: ${p}`);
+    }
+    const absolutePath = path.resolve(repoRoot, normalized);
+    if (!isPathInside(repoRoot, absolutePath)) {
+      throw new GitCommandError('path_outside_repo', `Path is outside repository root: ${p}`);
+    }
+    normalizedPaths.push(normalized);
+  }
+
+  await runGit(repo, ['checkout', '--', ...normalizedPaths], { cwd: repoRoot });
+  return { checkedOut: normalizedPaths };
+}
+
+async function gitGetRemoteUrl(workspace: string, remote: string): Promise<{ remoteUrl: string; remote: string }> {
+  const repo = await resolveGitRepository(workspace);
+  const result = await runGit(repo, ['remote', 'get-url', remote], { cwd: repo.repoRoot! });
+  const remoteUrl = result.stdout.trim();
+  if (!remoteUrl) {
+    throw new GitCommandError('git_command_failed', `Remote '${remote}' has no URL`);
+  }
+  return { remoteUrl, remote };
+}
+
 function formatOptionalGitLogRangeArg(flag: '--since' | '--until', value: string | undefined): string[] {
   return value ? [`${flag}=${value}`] : [];
 }

package/src/git/git-types.ts

@@ -150,4 +150,5 @@ export type GitCommandName =
   | 'git_checkpoint'
   | 'git_stash_push'
   | 'git_stash_pop'
-  | 'git_checkout_files';
+  | 'git_checkout_files'
+  | 'git_remote_url';

package/src/git/index.ts

@@ -70,3 +70,6 @@ export type {
   GitLogEntry,
   GitLogResult,
 } from './git-commands.js';
+
+export { TurnSnapshotTracker } from './turn-snapshot-tracker.js';
+export type { TurnCompletedCallback } from './turn-snapshot-tracker.js';

package/src/git/turn-snapshot-tracker.ts

@@ -0,0 +1,31 @@
+/**
+ * Tracks agent session status transitions and fires snapshot callbacks on turn completion.
+ * "Busy" = streaming | waiting_approval
+ * "Completed" = idle | error (transition from busy)
+ */
+
+export type TurnCompletedCallback = (params: { sessionId: string; workspace: string }) => void
+
+const BUSY_STATUSES = new Set(['streaming', 'waiting_approval'])
+const TERMINAL_STATUSES = new Set(['idle', 'error'])
+
+export class TurnSnapshotTracker {
+  private lastStatus = new Map<string, string>()
+  private onTurnCompleted: TurnCompletedCallback
+
+  constructor(onTurnCompleted: TurnCompletedCallback) {
+    this.onTurnCompleted = onTurnCompleted
+  }
+
+  record(sessionId: string, status: string, workspace: string | null | undefined): void {
+    const prev = this.lastStatus.get(sessionId)
+    this.lastStatus.set(sessionId, status)
+    if (workspace && prev && BUSY_STATUSES.has(prev) && TERMINAL_STATUSES.has(status)) {
+      this.onTurnCompleted({ sessionId, workspace })
+    }
+  }
+
+  forget(sessionId: string): void {
+    this.lastStatus.delete(sessionId)
+  }
+}

package/src/providers/contracts.d.ts

@@ -339,6 +339,14 @@ export interface ProviderModule {
     sessionProbe?: ProviderSessionProbe;
     /** Allow sending another prompt while the CLI is still generating so users can intervene mid-turn. */
     allowInputDuringGeneration?: boolean;
+    /** Delay before submitting typed CLI input (provider-specific TUI tuning) */
+    sendDelayMs?: number;
+    /** Submit key used after typing into CLI PTY (default: carriage return) */
+    sendKey?: string;
+    /** How the CLI adapter decides when to submit typed input */
+    submitStrategy?: 'wait_for_echo' | 'immediate';
+    /** If true, typed input must echo on the PTY screen before the adapter sends Enter. */
+    requirePromptEchoBeforeSubmit?: boolean;
     /** Approval button priority hints used when auto-approve must pick a positive action */
     approvalPositiveHints?: string[];
     scripts?: ProviderScripts;

package/src/providers/contracts.ts

@@ -450,6 +450,8 @@ export interface ProviderModule {
   sendKey?: string;
   /** How the CLI adapter decides when to submit typed input */
   submitStrategy?: 'wait_for_echo' | 'immediate';
+  /** If true, typed input must echo on the PTY screen before the adapter sends Enter. */
+  requirePromptEchoBeforeSubmit?: boolean;
   /** Keep this provider out of the upstream auto-updated bundle */
   /** @deprecated Machine-level provider source policy now lives in config.providerSourceMode. Local overrides shadow upstream by root precedence and should not rely on provider-level disableUpstream. */
   disableUpstream?: boolean;

package/src/providers/provider-schema.ts

@@ -59,6 +59,7 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'sendDelayMs',
   'sendKey',
   'submitStrategy',
+  'requirePromptEchoBeforeSubmit',
   'timeouts',
   'disableUpstream',
 ])