basant307/AI_Governance_Project

1/**2 * @license3 * Copyright 2025 Qwen4 * SPDX-License-Identifier: Apache-2.05 */6import type { Config } from '@qwen-code/qwen-code-core';7/**8 * Resolved metadata for a startup worktree. Returned to the caller so the9 * sidecar write (which needs `Config`) can happen after `loadCliConfig`.10 */11export interface StartupWorktreeContext {12    /** Resolved absolute worktree path (where `process.cwd()` now points). */13    worktreePath: string;14    /** Slug, e.g. `my-feature` or `pr-123`. */15    slug: string;16    /** Branch name, e.g. `worktree-my-feature` or `worktree-pr-123`. */17    branch: string;18    /** Repo top level captured before chdir. */19    repoRoot: string;20    /** Branch that was checked out at worktree-creation time. */21    originalBranch: string;22    /** HEAD SHA captured at worktree-creation time (for WorktreeExitDialog). */23    originalHeadCommit: string;24    /** True iff the input was a PR reference. */25    isPullRequest: boolean;26    /**27     * True when the worktree directory already existed at startup and we28     * re-attached to it. PR fetch is skipped29     * on re-attach since the ref was materialized previously, and30     * commit-count semantics in `WorktreeExitDialog` will track only this31     * session's new commits.32     */33    wasReattached: boolean;34}35export type SetupStartupWorktreeResult = {36    ok: true;37    context: StartupWorktreeContext;38} | {39    ok: false;40    error: string;41};42/**43 * Resolves slug, creates the worktree, switches `process.cwd()`, and returns44 * the metadata needed for the post-`loadCliConfig` sidecar write.45 *46 * Returns `null` when `rawInput === undefined` (no `--worktree` flag passed47 * at all). Returns `{ ok: false, error }` for validation / git failures so48 * the caller can print to stderr and exit with a controlled non-zero status.49 *50 * The caller is responsible for chdir-ing back if a later step fails — this51 * helper does not roll back the worktree directory on a downstream error,52 * matching `EnterWorktreeTool`'s "the worktree is yours now" semantics.53 */54export interface SetupStartupWorktreeOptions {55    /**56     * Mirrors `worktree.symlinkDirectories` (Phase D-2). Forwarded to57     * `createUserWorktree` so the new worktree gets the same opt-in58     * symlinks as `enter_worktree` and agent isolation worktrees do.59     */60    symlinkDirectories?: readonly string[];61}62export declare function setupStartupWorktree(rawInput: string | undefined, options?: SetupStartupWorktreeOptions): Promise<SetupStartupWorktreeResult | null>;63/**64 * Result of the post-`loadCliConfig` sidecar persist step. Callers use the65 * boolean fields to decide whether to surface an INFO line in TUI / a66 * `<system-reminder>` in headless / a `pendingWorktreeNotice` in ACP.67 */68export interface PersistStartupWorktreeResult {69    /** True when a pre-existing sidecar was found and overridden. */70    overrodeResumedWorktree: boolean;71    /**72     * Slug of the worktree that was overridden, when {@link overrodeResumedWorktree}73     * is true. Used in the INFO message so users can re-attach to it if they74     * launched with `--worktree` by mistake.75     */76    overriddenSlug?: string;77    /** Path to the sidecar file just written. */78    sidecarPath: string;79}80/**81 * Writes the `WorktreeSession` sidecar that Phase C's `--resume` restore82 * machinery consumes, and tags the worktree directory with the current83 * session ID so cross-session `exit_worktree action="remove"` is refused.84 *85 * Handles the `--worktree` × `--resume` precedence: when a sidecar already86 * exists (the user resumed a session that previously had a different87 * worktree), the new context wins and the previous slug is reported back88 * so callers can show an INFO line.89 */90export declare function persistStartupWorktreeSidecar(config: Config, context: StartupWorktreeContext): Promise<PersistStartupWorktreeResult>;91/**92 * Builds the one-shot context message that gets injected into the model on93 * the first user prompt (TUI: INFO history item + reminder prefix; headless:94 * `<system-reminder>` prefix + JSON event; ACP currently exits before95 * reaching this code path — see the `--worktree` × `--acp` mutex check96 * in `gemini.tsx`).97 *98 * Mirrors `restoreWorktreeContext`'s contextMessage shape so resumed-with-99 * worktree and started-with-worktree sessions read identically to the model.100 *101 * Differentiates the verb based on whether the worktree was just created102 * or the CLI re-attached to a pre-existing one — same slug + branch but103 * meaningfully different user intent. The override addendum (when104 * `--worktree` clobbered a resumed session's prior worktree) is shown105 * regardless of created/reattached state.106 *107 * Parameter type is `Pick<StartupWorktreeContext, …>` rather than the full108 * context so test fixtures can construct minimal literals without109 * tracking every internal field. Adding fields to {@link110 * StartupWorktreeContext} should NOT force test-fixture churn here.111 */112export declare function buildStartupWorktreeNotice(context: Pick<StartupWorktreeContext, 'slug' | 'worktreePath' | 'branch' | 'wasReattached'>, override?: PersistStartupWorktreeResult): string;113