export type MutationAgentRole = "explorer" | "mutation_worker" | "coordinator" | "proposal"; export type MutationLeaseState = "active" | "proposal_only" | "pending_merge" | "merged" | "released"; export interface MutationWorkerContract { role: MutationAgentRole; ownerAgentId: string; taskId?: string; ownedFiles: string[]; ownedDirs: string[]; forbiddenFiles: string[]; forbiddenDirs: string[]; expectedArtifacts: string[]; verifierCommand?: string; expectedOutputArtifact?: string; mergeStrategy?: string; stopCondition?: string; artifactKeys: string[]; leaseState: MutationLeaseState; baseHash?: string; expiresAt?: string; worktreePath?: string; proposalMode: boolean; } export interface MutationContractValidation { valid: boolean; errors: string[]; } export interface MutationScopeCheck { allowed: boolean; reason?: string; offendingPath?: string; reasonClass?: "mutation_scope_conflict" | "proposal_mode_required"; } export interface ShellMutationPathExtraction { mutates: boolean; paths: string[]; unknownMutation: boolean; reason?: string; } /** * A shell command can syntactically contain a write while leaving no durable * project delta (for example `cat > test/probe.mjs; node test/probe.mjs; rm * test/probe.mjs`). Safety checks need the attempted write; controller state * needs the observed post-command truth. Keep those facts separate. */ export interface ShellMutationObservation { attempted: boolean; attemptedPaths: string[]; effectivePaths: string[]; transientPaths: string[]; unknownPaths: string[]; basis: "path_fingerprint" | "unavailable"; } /** * Reduce a static shell-write extraction and pre/post path fingerprints into * durable mutation truth. `missing` is an explicit state, not an absent * sample, so a create-and-remove probe is distinguishable from an unreadable * path. Callers may use content hashes for files and stat signatures for * directories. */ export declare function observeShellMutation(extraction: ShellMutationPathExtraction, before: ReadonlyMap, after: ReadonlyMap): ShellMutationObservation; export interface DelegationMutationScopeDerivation { args: Record; changed: boolean; mutationLikely: boolean; proposalOnly: boolean; ownedFiles: string[]; ownedDirs: string[]; reason?: string; } export declare function normalizeMutationPath(root: string, pathValue: string): string; export declare function parseMutationWorkerContract(args: Record, options?: { workingDir?: string; ownerAgentId?: string; subagentType?: string; defaultProposalMode?: boolean; }): MutationWorkerContract; export declare function validateMutationWorkerContract(contract: MutationWorkerContract): MutationContractValidation; export declare function mutationScopesOverlap(left: Pick, right: Pick): boolean; export declare function coordinatorOwnedArtifactReason(pathValue: string): string | null; export declare function checkMutationScope(contract: MutationWorkerContract | null | undefined, paths: string[], options?: { workingDir?: string; proposalMode?: boolean; }): MutationScopeCheck; export declare function checkShellMutationScope(contract: MutationWorkerContract | null | undefined, command: string, options?: { workingDir?: string; proposalMode?: boolean; }): MutationScopeCheck & { extraction: ShellMutationPathExtraction; }; export declare function mutationContractToEnv(contract: MutationWorkerContract): Record; export declare function mutationContractFromEnv(env?: NodeJS.ProcessEnv, workingDir?: string): MutationWorkerContract | null; export declare function deriveDelegationMutationScope(args: Record, options?: { workingDir?: string; defaultVerifierCommand?: string | null; enabled?: boolean; }): DelegationMutationScopeDerivation; export declare function renderMutationContractForPrompt(contract: MutationWorkerContract): string; export declare function detectWorkspaceDestructiveCommand(command: string, workspaceRoot?: string): string | null; export declare function extractShellMutationPaths(command: string, options?: { workingDir?: string; }): ShellMutationPathExtraction; export declare function isShellCommandLikelyMutatingFilesystem(command: string): boolean;