@quantiya/codevibe-core 2.0.1 → 2.0.2

package/dist/local-model/manager.d.ts

@@ -0,0 +1,119 @@
+import { spawn } from 'child_process';
+import type { Tier } from '../orchestration-shell/types';
+import { type LocalModelState, type LocalModelStateStore } from './state';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export type LocalModelCommand = 'install' | 'status' | 'remove' | 'enable' | 'warm' | 'health-check';
+export type LocalModelEntitlementSource = 'backend' | 'unauthenticated' | 'unavailable';
+export interface LocalModelEntitlement {
+    tier: Tier | 'UNKNOWN';
+    source: LocalModelEntitlementSource;
+}
+export interface LocalModelArtifactConfig {
+    artifactId: string | null;
+    downloadUrl: string | null;
+    sha256: string | null;
+    expectedBytes?: number | null;
+    cacheDir: string;
+    ollamaModel?: string | null;
+}
+export interface LocalModelStore {
+    artifactExists(config: LocalModelArtifactConfig): Promise<boolean>;
+    removeArtifact(config: LocalModelArtifactConfig): Promise<boolean>;
+}
+export interface LocalModelInstaller {
+    install(config: LocalModelArtifactConfig): Promise<void>;
+}
+export interface LocalModelDownloadTransport {
+    downloadToFile(url: URL, destinationPath: string, expectedBytes: number): Promise<void>;
+}
+export interface LocalModelRuntimeFactory {
+    createRunner(config: LocalModelArtifactConfig): Promise<LocalGemmaPlannerRunner | null>;
+}
+export interface RunLocalModelCommandOptions {
+    command: LocalModelCommand;
+    entitlement: LocalModelEntitlement;
+    config?: LocalModelArtifactConfig;
+    store?: LocalModelStore;
+    stateStore?: LocalModelStateStore;
+    installer?: LocalModelInstaller;
+    runtimeFactory?: LocalModelRuntimeFactory;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+    /** TEST SEAM — the capability-aware default model for a BARE install. Defaults to
+     *  {@link resolveDefaultOllamaModelForInstall}; tests inject a deterministic thunk. */
+    resolveInstallModel?: () => Promise<string>;
+}
+export declare function loadLocalModelArtifactConfigFromEnv(env?: NodeJS.ProcessEnv): LocalModelArtifactConfig;
+/** The curated local-planner Ollama models (benchmarked 2026-07-02, gemma4 family). */
+export declare const CAPABLE_OLLAMA_MODEL = "gemma4:12b-it-qat";
+export declare const BASELINE_OLLAMA_MODEL = "gemma4:latest";
+/** True iff the Ollama version string (e.g. "0.31.1", tolerating a leading "v") is ≥ MIN_OLLAMA_MAJOR.MINOR. */
+export declare function ollamaVersionAtLeast(version: string | undefined, major?: number, minor?: number): boolean;
+/**
+ * The DEFAULT Ollama model for `codevibe model install` when the user set neither
+ * `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` nor a pinned artifact — CAPABILITY-AWARE per the
+ * CP-4 plan (2026-07-02 benchmark): the stronger 12B QAT (`gemma4:12b-it-qat`) ONLY when
+ * the host has enough RAM (~16 GB) AND Ollama ≥ 0.31 (the 12B tags need it — 0.24 rejects
+ * the pull); otherwise the broadly-compatible 8B (`gemma4:latest`). Fails SOFT to the 8B
+ * on any uncertainty (Ollama unreachable / unparseable version) so install never breaks.
+ */
+export declare function resolveDefaultOllamaModelForInstall(deps?: {
+    ollamaHost?: string;
+    totalMemBytes?: number;
+    fetchImpl?: typeof fetch;
+    log?: (s: string) => void;
+}): Promise<string>;
+export declare function isLocalModelEntitled(entitlement: LocalModelEntitlement): entitlement is LocalModelEntitlement & {
+    tier: 'PRO' | 'MAX';
+};
+export declare function localModelArtifactPath(config: LocalModelArtifactConfig): string | null;
+export declare const defaultLocalModelStore: LocalModelStore;
+export declare const defaultLocalModelDownloadTransport: LocalModelDownloadTransport;
+export interface LocalModelProcessPuller {
+    pull(model: string, localOllamaHost?: string): Promise<void>;
+}
+type SpawnOllamaPull = typeof spawn;
+export declare class OllamaProcessPuller implements LocalModelProcessPuller {
+    private readonly command;
+    private readonly spawnPull;
+    constructor(command?: string, spawnPull?: SpawnOllamaPull);
+    pull(model: string, localOllamaHost?: string): Promise<void>;
+}
+/**
+ * Build the Ollama runtime config for a pull that HONORS the caller's `model` argument
+ * (the config/CLI is authoritative), sourcing host + timeout from env. Without this, the
+ * pullers re-read `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` from env — which is UNSET on a bare
+ * `codevibe model install`, so the capability-resolved default (12B/8B) would never reach
+ * the puller and the install would throw. For an explicit install the arg equals the env
+ * model → identical result. Host (default 127.0.0.1) + timeout (default) resolve when unset.
+ */
+export declare function ollamaEnvForModel(model: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Fill an env-derived artifact config's `ollamaModel` + `artifactId` from PERSISTED state
+ * when env didn't supply them — so a bare `codevibe model install` (which recorded the
+ * resolved model in state) is usable by the shell + status/enable/warm without the user
+ * setting `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL`. Env ALWAYS wins (explicit override); state
+ * only fills the gaps, and only when a model was actually installed (`choice === 'enabled'`).
+ */
+export declare function applyPersistedSelection(config: LocalModelArtifactConfig, state: Pick<LocalModelState, 'choice' | 'artifactId' | 'ollamaModel'>): LocalModelArtifactConfig;
+export declare class DefaultOllamaPuller implements LocalModelProcessPuller {
+    private readonly httpPuller;
+    private readonly processPuller;
+    constructor(httpPuller?: LocalModelProcessPuller, processPuller?: LocalModelProcessPuller);
+    pull(model: string): Promise<void>;
+}
+export declare class OllamaLocalModelInstaller implements LocalModelInstaller {
+    private readonly puller;
+    constructor(puller?: LocalModelProcessPuller);
+    install(config: LocalModelArtifactConfig): Promise<void>;
+}
+export declare class HttpsLocalModelInstaller implements LocalModelInstaller {
+    private readonly transport;
+    constructor(transport?: LocalModelDownloadTransport);
+    install(config: LocalModelArtifactConfig): Promise<void>;
+    private tryDigestExistingArtifact;
+}
+export declare const defaultLocalModelInstaller: LocalModelInstaller;
+export declare const defaultLocalModelRuntimeFactory: LocalModelRuntimeFactory;
+export declare function runLocalModelCommand(options: RunLocalModelCommandOptions): Promise<number>;
+export {};

package/dist/local-model/ollama.d.ts

@@ -0,0 +1,27 @@
+import type { PlannerProbeResult } from '../planner/adapter';
+import type { LocalGemmaAdvisoryOptions } from '../planner/local-advisory';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export interface OllamaRuntimeConfig {
+    model: string;
+    host: string;
+    timeoutMs: number;
+}
+export type OllamaRuntimeConfigResult = {
+    ok: true;
+    config: OllamaRuntimeConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function isSafeOllamaModelName(model: string | null | undefined): model is string;
+export declare function parseLocalOllamaHost(raw: string | undefined): string | null;
+export declare function loadOllamaRuntimeConfigFromEnv(env?: NodeJS.ProcessEnv): OllamaRuntimeConfigResult;
+export declare function requestOllamaPull(config: OllamaRuntimeConfig): Promise<void>;
+export declare class OllamaGemmaPlannerRunner implements LocalGemmaPlannerRunner {
+    private readonly config;
+    readonly runtimeLabel: string;
+    constructor(config: OllamaRuntimeConfig);
+    classify(promptText: string): Promise<string>;
+    generateAdvisory(promptText: string, options?: LocalGemmaAdvisoryOptions): Promise<string>;
+    probe(): Promise<PlannerProbeResult>;
+}

package/dist/local-model/runtime.d.ts

@@ -0,0 +1,27 @@
+import type { PlannerProbeResult } from '../planner/adapter';
+import type { LocalGemmaAdvisoryOptions } from '../planner/local-advisory';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export interface LocalGemmaRuntimeConfig {
+    command: string;
+    args: string[];
+    modelPath: string;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+}
+export type LocalGemmaRuntimeConfigResult = {
+    ok: true;
+    config: LocalGemmaRuntimeConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function loadLocalGemmaRuntimeConfigFromEnv(modelPath: string, env?: NodeJS.ProcessEnv): LocalGemmaRuntimeConfigResult;
+export declare class LocalGemmaProcessRunner implements LocalGemmaPlannerRunner {
+    private readonly config;
+    readonly runtimeLabel: string;
+    constructor(config: LocalGemmaRuntimeConfig);
+    classify(promptText: string): Promise<string>;
+    generateAdvisory(promptText: string, options?: LocalGemmaAdvisoryOptions): Promise<string>;
+    probe(): Promise<PlannerProbeResult>;
+    private invoke;
+}

package/dist/local-model/state.d.ts

@@ -0,0 +1,32 @@
+export type LocalModelChoice = 'not_configured' | 'skipped' | 'enabled';
+export interface LocalModelState {
+    schemaVersion: 1;
+    choice: LocalModelChoice;
+    artifactId: string | null;
+    /**
+     * The installed Ollama model tag (e.g. `gemma4:12b-it-qat`), persisted so a BARE
+     * `codevibe model install` (which resolves the model dynamically, not from env) is
+     * usable afterward — the shell + status/enable/warm resolve it from here when
+     * `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` is unset. Null for non-Ollama / legacy state.
+     */
+    ollamaModel: string | null;
+    updatedAt: string;
+}
+export interface LocalModelStateStore {
+    read(): Promise<LocalModelState>;
+    write(state: LocalModelState): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function defaultLocalModelState(): LocalModelState;
+export declare function localModelStateFilePath(env?: NodeJS.ProcessEnv): string;
+export declare class FileSystemLocalModelStateStore implements LocalModelStateStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    read(): Promise<LocalModelState>;
+    write(state: LocalModelState): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare const defaultLocalModelStateStore: LocalModelStateStore;
+export declare function readLocalModelState(store?: LocalModelStateStore): Promise<LocalModelState>;
+export declare function markLocalModelEnabled(artifactId: string | null, ollamaModel?: string | null, store?: LocalModelStateStore): Promise<void>;
+export declare function markLocalModelSkipped(store?: LocalModelStateStore): Promise<void>;

package/dist/orchestration/detect-agents.d.ts

@@ -1,7 +1,7 @@
 import { Logger } from '../logger';
 import { AppSyncClient } from '../appsync';
 import { CapabilityRegistry } from '../adapter/capabilities';
-export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX';
+export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY';
 /**
  * Returns the subset of agents present on PATH. Uses `command -v`
  * (POSIX-standard) rather than `which` for portability across macOS
@@ -22,12 +22,25 @@ export declare function detectInstalledAgents(): DetectableAgent[];
  * and log but not abort startup — Quorum 2.0 auto-enable degrades
  * to "use last-pushed agent set" when the mutation fails).
  *
+ * CP-1.f LOCK RP-3 — `replace` semantics. `User.availableAgents` is a
+ * cross-device UNION by default (`replace=false`), which never removes a
+ * stale agent (a `GEMINI` from a prior device/install would linger and
+ * get composed into the reviewer panel → `spawn gemini ENOENT`). The
+ * orchestration shell passes `replace=true` so the stored set is EXACTLY
+ * the current orchestration host's installed agents, AND — also per
+ * RP-3 — always writes even on zero detection (no skip-on-empty) so a
+ * stale set cannot linger. The 1.x companion-daemon callers keep the
+ * default `replace=false` (union) path, preserving their contract.
+ *
  * @param client  AppSyncClient that's already been authenticated via
  *                authenticateWithStoredTokens()
  * @param log     Logger — warn-level when no agents detected, info
  *                on success
+ * @param replace When true (orchestration shell), REPLACE the stored set
+ *                with exactly the detected set and write even when empty.
+ *                Default false (1.x companion union path).
  */
-export declare function pushDetectedAgents(client: AppSyncClient, log: Pick<Logger, 'info' | 'warn'>, capabilityRegistry?: CapabilityRegistry, detectFn?: () => DetectableAgent[]): Promise<void>;
+export declare function pushDetectedAgents(client: AppSyncClient, log: Pick<Logger, 'info' | 'warn'>, capabilityRegistry?: CapabilityRegistry, detectFn?: () => DetectableAgent[], replace?: boolean): Promise<void>;
 /**
  * Quorum 2.0 (2f.0.a.6) per-session orchestration CLI override applier.
  * All three plugin wrappers (`codevibe-claude`, `codevibe-gemini`,

package/dist/orchestration/setup-types.d.ts

@@ -42,7 +42,8 @@ export declare const DEFAULT_ROLE_BY_SEAT: WizardRole[];
 /**
  * Canonical agent ordering used for wizard defaults. The first
  * installed agent in this order is the default for each seat unless
- * the user picks otherwise.
+ * the user picks otherwise. AGY-2.0: antigravity ranks LAST (weakest —
+ * defaulted only on an agy-only host), mirroring TIER2_REVIEWER_RANK.
  */
 export declare const AGENT_PRIORITY: AgentKind[];
 /**

package/dist/orchestration-shell/__tests__/attachments.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/audit-browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/audited-path-fixes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/bracketed-paste.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cli-group-halt-wiring.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cli-orchestration-session-bootstrap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cli-probe-group-status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cli-quorum-loop-tier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cli-verdict-classifier-wiring.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/context-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp10-585-accept-echo-target.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp10-585-loop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp10-585-prompts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp12-w2b-team-loop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp12-w4-team-recovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp1f-quorum-loop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp606-team-track-user-resolved.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/cp7-reviewer-substrate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/declared-test-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/familiarize-routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/gate-decision-submit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/gate-details-panel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/gate-verdict-details-dispatch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/group-decision-submit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/image-attach-e2e.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/input-bar-autocomplete.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/live-region-cap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/live-static-order.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/model-cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/non-gate-prompt-routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/orchestration-app-group-decision-transport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/orchestration-app-layout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/reissue-team-retained-spec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/review-summary-render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/reviewer-wizard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/reviewers-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/root-discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/serialize-submissions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/slash-suggest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/status-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/task-progress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/team-decompose-routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/team-decompose-types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/team-decompose.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/team-e2e-smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/tier2-reviewer-selection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/web-browsing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/attachments.d.ts

@@ -0,0 +1,152 @@
+import type { ImageAttachment } from './types';
+/** Per-file on-disk cap (§10.5). */
+export declare const MAX_IMAGE_BYTES: number;
+/** Max attachments on the FINAL accumulated+deduped task set (§5). */
+export declare const MAX_ATTACHMENTS = 8;
+/** Sniff the raster MIME from the first bytes. Returns null if not a known raster. */
+export declare function sniffImageMime(head: Buffer): {
+    mime: string;
+    ext: string;
+} | null;
+/**
+ * Extract candidate image-path SPANS from the raw text. Two passes:
+ *   1. single/double-quoted spans ending in an image extension;
+ *   2. on the remaining text (quoted spans masked out), bare / backslash-escaped
+ *      / `file://` / `~`-relative spans ending in an image extension.
+ * Returns the EXACT matched span (`rawToken`, incl. quotes/escapes) — the brief
+ * replacement (§8) rewrites this exact span.
+ */
+export declare function extractImagePathSpans(text: string): Array<{
+    rawToken: string;
+}>;
+export interface IngestReject {
+    token: string;
+    reason: string;
+}
+export interface IngestResult {
+    attachments: ImageAttachment[];
+    rejects: IngestReject[];
+}
+export interface IngestOptions {
+    cwd: string;
+    homedir: string;
+    /** ID minter (default `randomUUID`); injectable for deterministic tests. */
+    newId?: () => string;
+    /** Already-accumulated attachments (clarification loop) — for the FINAL count cap + sourcePath dedup (§5). */
+    existing?: ImageAttachment[];
+}
+/**
+ * Detect + validate image attachments in `text` (§4). UX-level validation
+ * (existsSync + regular-file + size + magic-sniff); the fd-safe `O_NOFOLLOW`
+ * re-validation at copy/base64 time (§7.3/§6) is the security boundary. Dedups by
+ * `sourcePath` (merging `rawTokens`) and enforces `MAX_ATTACHMENTS` on the FINAL
+ * accumulated set (`existing` ∪ newly-detected).
+ */
+export declare function detectImageAttachments(text: string, opts: IngestOptions): IngestResult;
+/**
+ * Build validated `ImageAttachment`s DIRECTLY from resolved absolute paths — no text
+ * tokenization (Stage-1 R2 M-1). Used for the §13 Option-2 InputBar chip: the paths
+ * are carried out-of-band, so re-serializing them through the text detector would
+ * mangle paths containing `"`/`\`. Each path is `path.resolve`d + validated via the
+ * SAME `promoteLexicalImagePath` (authoritative re-validation of the InputBar's
+ * optimistic check). Deduped by resolved path; `MAX_ATTACHMENTS` enforced.
+ */
+export declare function attachmentsFromPaths(paths: string[], opts?: {
+    newId?: () => string;
+    existing?: ImageAttachment[];
+}): IngestResult;
+/** Human advisory for a set of rejects (§4/§9) — a clear, actionable line per reject. */
+export declare function formatIngestRejects(rejects: IngestReject[]): string | null;
+/** The in-worktree attachments dir (§7). Excluded from BOTH diff-capture paths + promote. */
+export declare const SHADOW_ATTACHMENTS_DIR = ".codevibe-attachments";
+/** The AGENT-NEUTRAL in-worktree relative ref for an attachment (§7.2/§8). */
+export declare function attachmentRelPath(a: ImageAttachment): string;
+export interface CopiedAttachment {
+    id: string;
+    relPath: string;
+    mime: string;
+}
+export interface PreparedAttachments {
+    copiedAttachments: CopiedAttachment[];
+    failedAttachments: ImageAttachment[];
+    /** The brief with FAILED-copy refs rewritten to a neutral marker (no dangling ref). */
+    roundBrief: string;
+}
+/**
+ * Per-round copy + failure-rewrite in ONE step (§7.3, rev-7). For each attachment,
+ * fd-copy (the §6/§7.3 `O_NOFOLLOW` + byte-ceiling + re-sniff re-validation) into
+ * `<shadowDir>/.codevibe-attachments/<id>.<ext>` via a temp + atomic rename; for a
+ * FAILED copy, unlink the partial dest AND rewrite that attachment's neutral rel-ref
+ * in `roundBrief` to `[attached image skipped]` (so no dangling ref survives). The
+ * returned `roundBrief` (failures neutralized) feeds BOTH the per-agent stdin AND
+ * the execute-first payload. Never throws / never hard-blocks.
+ */
+export declare function prepareAttachmentsForSpawn(roundBrief: string, attachments: ImageAttachment[], shadowDir: string): PreparedAttachments;
+/**
+ * Per-agent rendering of the copied-attachment refs, appended to the brief at spawn
+ * (§7.2). The stored/canonical brief is agent-NEUTRAL (`.codevibe-attachments/<id>.<ext>`);
+ * this adds the agent-specific pointer: Claude/Codex → an `Attached images:` list of
+ * relative paths (read via their Read tool); Gemini → the `@./…` form.
+ */
+export declare function renderAttachmentsForAgent(agent: string, copied: CopiedAttachment[], workdir?: string): string;
+/**
+ * The TEAM-DECOMPOSER brief transform (§7.5). The decomposition implementor runs
+ * in the REAL repo (no shadow, no copy), so it must NOT see an in-worktree ref OR
+ * an absolute path — replace every typed image token with a text-only marker. The
+ * ACTUAL images flow to the implementing track(s) via the group attachment set;
+ * the decomposer only needs to know an image exists so it routes work sensibly.
+ */
+export declare function stripAttachmentsForDecomposer(brief: string, attachments: ImageAttachment[]): string;
+/**
+ * Replace every typed image rawToken span (across the turn + clarification answers)
+ * with the AGENT-NEUTRAL in-worktree relative ref (§8) so no absolute `/Users/…`
+ * path leaks into a brief that gets stored / encrypted / sent to an implementor.
+ * Used by `composeImplementationBrief` AND (Stage-2 R1 HIGH-2) by the team-launch
+ * path to sanitize the manual `/team` per-track briefs, which never pass through
+ * `composeImplementationBrief`.
+ */
+export declare function rewriteAttachmentTokensToRefs(brief: string, attachments: ImageAttachment[]): string;
+/**
+ * §13 Option-2 — replace each `[Image #N]` chip token with the ref of the attachment
+ * for the N-th CARRIED PATH. `orderedPaths` is the ordered-with-DUPLICATES resolved
+ * carried-path list aligned 1:1 with the chip numbers in `brief` (the InputBar
+ * renumbers chips densely in reading order at submit, and the shell accumulates +
+ * cross-turn-renumbers across a clarification so numbers are globally unique). Keying
+ * on the carried PATH (then resolving to the deduped attachment) — rather than a
+ * deduped `attachments[N-1]` index — is what makes a DUPLICATE same-file drag
+ * (`images=[A,A,B]` → dedup `[A,B]`) map `#1→A #2→A #3→B` correctly (Stage-2 R5), and
+ * a cross-turn accumulation map each turn's image to its own ref (the multi-turn case).
+ * An out-of-range N or an unknown path (a typed literal `[Image #99]`) degrades to a
+ * neutral marker — never a wrong ref. Run AFTER `rewriteAttachmentTokensToRefs`; the
+ * two token classes (typed raw-path spans vs `[Image #N]` chips) are disjoint.
+ */
+export declare function rewriteChipTokensByNumber(brief: string, orderedPaths: string[], attachments: ImageAttachment[]): string;
+/** Per-model-call total base64-source cap (§6): base64 inflates ~33%; distinct from the 10 MB per-file copy cap. */
+export declare const MAX_BASE64_SOURCE_BYTES: number;
+/**
+ * The SECURITY-boundary read (§4/§6/§7.3): open the LEXICAL absolute path with
+ * `O_RDONLY | O_NOFOLLOW` (refuses if the final component is a symlink — defeats a
+ * post-ingest swap to a symlink-to-`/etc/…`), `fstat` the FD (re-check
+ * regular-file), read with a running byte ceiling (defends a file that grew after
+ * ingest), and re-sniff the magic bytes from the FD. NEVER a naive
+ * `fs.readFile(sourcePath)`. Throws on any violation. Shared by the base64 read
+ * (§6) and the copy-into-shadow path (§7.3).
+ */
+export declare function readImageFdSafe(sourcePath: string, maxBytes?: number): {
+    buf: Buffer;
+    mime: string;
+};
+/**
+ * Shell-layer helper (§6): read the attachments fd-safe and return RAW base64
+ * (NO `data:` prefix — Ollama's `images[]` wants raw base64) for the LOCAL model,
+ * under a per-call total-source-bytes cap + a count cap (first-N-under-cap). Any
+ * attachment that fails the fd-safe read is returned in `failed` — callers
+ * proceed text-only with a content-free advisory, never block/throw.
+ */
+export declare function attachmentsToBase64(attachments: ImageAttachment[], opts?: {
+    maxTotalBytes?: number;
+    maxCount?: number;
+}): {
+    images: string[];
+    failed: ImageAttachment[];
+};