@quantiya/codevibe-core 2.0.7 → 2.0.9

package/dist/local-executor/anchored-fs.d.ts

@@ -0,0 +1,250 @@
+import { type WorkspaceRootAuthority } from './workspace-authority.js';
+type PublicationPrivateRetirementStage = 'commit-rename' | 'commit-unlink' | 'commit-sync' | 'pending-rename' | 'pending-unlink' | 'pending-sync' | 'retiring-rename' | 'retiring-unlink' | 'retiring-sync' | 'disposed-rename' | 'disposed-unlink' | 'disposed-sync';
+export interface AnchoredPublicationAuthorityResidue {
+    recordName: string;
+    authorityId: string;
+    targetParentCanonicalPath?: string;
+    targetName?: string;
+    /** Caller label for an authority-id owner-prefix match. */
+    ownerLabel?: string;
+    /** Read/schema failure retained for a scoped, therefore attributable, record. */
+    unresolvedDetail?: string;
+}
+/**
+ * Fresh bounded inventory of private publication records targeting exact
+ * durable parent paths or carrying exact caller-owner fingerprints. Teardown
+ * uses this only after all owned writers have drained; any remaining record is
+ * therefore retained authority, not a cache. Owner fingerprints are encoded in
+ * the record name before its body is written, so partial/non-JSON staging
+ * remains visible without adopting unrelated private records.
+ */
+export declare function listAnchoredPublicationAuthorityResidueForParents(parentCanonicalPaths: readonly string[], owners?: readonly {
+    ownerKey: string;
+    label: string;
+}[]): Promise<AnchoredPublicationAuthorityResidue[]>;
+export declare class AnchoredFileRemovalDurabilityError extends Error {
+    readonly code = "EANCHOREDFILEREMOVALDURABILITY";
+    readonly removed = true;
+    readonly durabilityUncertain = true;
+    constructor(message: string);
+}
+export declare function isAnchoredFileRemovalDurabilityError(err: unknown): err is AnchoredFileRemovalDurabilityError;
+export interface AnchoredFsIdentity {
+    dev: string;
+    ino: string;
+    /** Optional inode-reuse fence. Snapshot-root deletion always supplies it. */
+    birthtimeNs?: string;
+    /** Optional canonical-name binding, checked immediately before tree rename. */
+    canonicalPath?: string;
+}
+export interface AnchoredPathIdentity extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    mtimeMs: number;
+    kind: 'file' | 'directory';
+}
+export interface AnchoredCommittedFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    mode: number;
+    mtimeMs: number;
+    sha256: string;
+}
+export interface AnchoredReadFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    bytes: Buffer;
+    mode: number;
+    mtimeMs: number;
+    /** Exact immediate parent inode that owned the file throughout the read. */
+    parent: AnchoredFsIdentity & {
+        birthtimeNs: string;
+        canonicalPath: string;
+    };
+}
+export interface AnchoredHashedFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    sha256: string;
+    size: number;
+    mode: number;
+    mtimeMs: number;
+    parent: AnchoredFsIdentity & {
+        birthtimeNs: string;
+        canonicalPath: string;
+    };
+}
+/** Complete same-request witness required when opening an enumerated file. */
+export interface AnchoredFileWitness extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    size: bigint;
+    mtimeNs: string;
+    ctimeNs: string;
+    nlink: string;
+}
+/** True only when a failed atomic write deliberately left fail-closed recovery authority. */
+export declare function isUnresolvedAnchoredPublicationError(err: unknown): boolean;
+/** Read one bounded file through the deadline helper and return its bytes. */
+export declare function anchoredReadFileWithinRoot(root: string, relativePath: string, opts: {
+    maxBytes: number;
+    expectedRoot?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Exact enumerated leaf incarnation that must be opened. */
+    expectedFile?: AnchoredFileWitness;
+    /** Reject a multiply-linked leaf throughout the complete read. */
+    requireSingleLink?: boolean;
+    beforeOpen?: () => Promise<void> | void;
+    beforeAbsent?: () => Promise<void> | void;
+    afterStat?: () => Promise<void> | void;
+    afterRead?: () => Promise<void> | void;
+    helperTimeoutMs?: number;
+    testHangBeforeRead?: boolean;
+    testHangStage?: 'open' | 'read' | 'close';
+}): Promise<AnchoredReadFile | null>;
+/** Stream and hash one bounded file entirely in the deadline helper. */
+export declare function anchoredHashFileWithinRoot(root: string, relativePath: string, opts: {
+    maxBytes: number;
+    expectedRoot?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    beforeOpen?: () => Promise<void> | void;
+    afterStat?: () => Promise<void> | void;
+    afterRead?: () => Promise<void> | void;
+    helperTimeoutMs?: number;
+    testHangStage?: 'open' | 'read' | 'close';
+}): Promise<AnchoredHashedFile | null>;
+export type AnchoredWritePrecondition = {
+    kind: 'absent';
+} | {
+    kind: 'existing';
+    dev: string;
+    ino: string;
+    mode: number;
+    sha256: string;
+};
+export declare function captureAnchoredIdentity(target: string, opts?: {
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic parent-preflight stall seam. */
+    testHangBeforeReady?: boolean;
+    expectedType?: 'file' | 'directory';
+    /** Full parent incarnation for root-relative stat consumers. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal after missing child, before public-parent re-authentication. */
+    beforeAbsent?: () => Promise<void> | void;
+}): Promise<AnchoredPathIdentity>;
+/** Create or reopen one real direct-child directory under an exact parent. */
+export declare function anchoredEnsureDirectory(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<WorkspaceRootAuthority>;
+export interface AnchoredEnsuredDirectory {
+    authority: WorkspaceRootAuthority;
+    /** True only when this exact anchored helper invocation won the mkdir. */
+    created: boolean;
+}
+/**
+ * Create or reopen one real direct-child directory while reporting mkdir
+ * ownership from inside the anchored helper, not from a caller-side stat.
+ */
+export declare function anchoredEnsureDirectoryWithOwnership(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<AnchoredEnsuredDirectory>;
+/** Create one new direct-child directory without adopting a pre-existing name. */
+export declare function anchoredCreateDirectory(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<WorkspaceRootAuthority>;
+export declare function captureAnchoredWritePrecondition(filePath: string, maxBytes: number, afterStat?: () => Promise<void> | void, expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority): Promise<AnchoredWritePrecondition>;
+export declare function anchoredAtomicWrite(filePath: string, data: string | Buffer, opts: {
+    expected: AnchoredWritePrecondition;
+    mode?: number;
+    beforeCommit?: () => Promise<void> | void;
+    /** @internal deterministic seam after exact-state validation while the cross-process lock is held. */
+    afterValidation?: () => Promise<void> | void;
+    /** @internal bypass only for cross-process lock regression tests. */
+    serializeInProcess?: boolean;
+    /** @internal deterministic helper-crash seam for stale-temp recovery tests. */
+    crashAfterTempStage?: 'create' | 'write' | 'fsync';
+    /** @internal simulate disagreement from a repeated native owner probe. */
+    testMismatchedCurrentTempOwnerHash?: boolean;
+    /** @internal deterministic seam once an independent helper is waiting on the writer fence. */
+    afterLockContention?: () => Promise<void> | void;
+    /** @internal deterministic independent commit-authority crash seam. */
+    crashPublicationCommitStage?: 'create' | 'partial-write' | 'fsync';
+    /** @internal deterministic committed-cleanup crash seam. */
+    crashPublicationRetirementStage?: 'temp' | 'recovery' | 'quarantine' | 'marker' | 'commit';
+    /** @internal deterministic private transaction crash seam. */
+    crashPublicationPrivateRetirementStage?: PublicationPrivateRetirementStage;
+    /** @internal deterministic seam before committed prepared-temp disposition. */
+    beforePreparedTempRetirement?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic seam at the final temp-name disposition boundary. */
+    beforePreparedTempFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal after desktop proof is durable, immediately before guard unlink. */
+    beforePublicationAuthorityFinalization?: (tempPath: string) => Promise<void> | void;
+    /** Exact parent directory that must own the mutation. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Maximum existing/temp target bytes the helper may read or hash. */
+    maxTargetBytes: number;
+    /**
+     * Stable task/session ownership key for private crash authority. It is
+     * hashed before crossing the helper boundary and never written verbatim.
+     */
+    publicationOwnerKey?: string;
+    /** @internal deterministic post-publication directory-fsync failure seam. */
+    failDirectorySync?: boolean;
+    /** @internal deterministic seam immediately before an exact final unlink. */
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    /** @internal exact syscall seam before an existing target is quarantined. */
+    beforeTargetQuarantine?: (targetPath: string, quarantinePath: string) => Promise<void> | void;
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic blocked-helper seam. */
+    testHangBeforeReady?: boolean;
+}): Promise<AnchoredCommittedFile>;
+/**
+ * Hold one crash-reclaimable, inode-anchored cross-process lock for the full
+ * lifetime of `operation`. The callback process and its OS creation identity
+ * own the lock; the helper merely performs anchored acquisition/release. A
+ * helper crash cannot split the fence, and PID reuse cannot inherit it.
+ * The lock file itself carries no application authority.
+ */
+export declare function withAnchoredExclusiveLock<T>(lockPath: string, operation: () => Promise<T>, opts?: {
+    /** Maximum time to wait for another live owner; ownership itself has no lease. */
+    acquireTimeoutMs?: number;
+    /** Exact parent directory that must contain the lock. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Cancel only while waiting to acquire; once entered, `operation` owns shutdown semantics. */
+    signal?: AbortSignal;
+    /** @internal deterministic seam immediately before exact lock-artifact removal. */
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    /** @internal kill the acquisition helper after LOCKED to prove owner continuity. */
+    crashHelperAfterAcquire?: boolean;
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+}): Promise<T>;
+export declare function anchoredRemoveTree(target: string, identity: WorkspaceRootAuthority, opts?: {
+    beforeCommit?: () => Promise<void> | void;
+    afterRename?: (tombstonePath: string) => Promise<void> | void;
+    /** @internal lower deterministic helper/tree-cleaner deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic blocked-helper seam. */
+    testHangBeforeReady?: boolean;
+    /** @internal deterministic blocked recursive tree-cleaner seam. */
+    testHangTreeCleaner?: boolean;
+}): Promise<void>;
+export declare function anchoredRemoveFile(filePath: string, expectedIdentity?: AnchoredFsIdentity, opts?: {
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal deterministic post-unlink directory-fsync failure seam. */
+    failDirectorySync?: boolean;
+}): Promise<void>;
+/** Reclaim dead helper temp/lock/release/token residue for one anchored marker path. */
+export declare function anchoredCleanupWriteArtifacts(filePath: string, opts?: {
+    waitForLive?: boolean;
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    helperTimeoutMs?: number;
+    /** Exact parent directory that must own every recovered artifact. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal deterministic restart-disposition race seam. */
+    beforePreparedTempFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic final guard-link race seam. */
+    beforePublicationAuthorityFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic private transaction crash seam. */
+    crashPublicationPrivateRetirementStage?: PublicationPrivateRetirementStage;
+}): Promise<void>;
+export declare function anchoredRemoveEmptyDirectory(dir: string, expectedIdentity?: AnchoredFsIdentity, opts?: {
+    /** Exact parent directory that must own the retiring child. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+}): Promise<void>;
+export {};

package/dist/local-executor/bounded-directory.d.ts

@@ -0,0 +1,78 @@
+import type { Dirent } from 'node:fs';
+import type { WorkspaceRootAuthority } from './workspace-authority.js';
+/** Shared metadata ceilings for every CodeVibe-owned filesystem traversal. */
+export declare const MAX_METADATA_ENTRY_COUNT = 100000;
+export declare const MAX_METADATA_PATH_BYTES: number;
+export interface MetadataBudget {
+    entries: number;
+    utf8PathBytes: number;
+    readonly maxEntries: number;
+    readonly maxUtf8PathBytes: number;
+}
+export declare function createMetadataBudget(maxEntries?: number, maxUtf8PathBytes?: number): MetadataBudget;
+/**
+ * Retry a complete read-only operation when a bounded directory keeps the same
+ * authenticated inode but gains or loses a child during one enumeration.
+ *
+ * The operation must create fresh metadata budgets on every invocation. Only
+ * same-inode content churn is retried: root replacement, identity loss,
+ * malformed authority, helper timeout, and every other failure remain
+ * immediate and fail closed.
+ */
+export declare function withTransientDirectoryEnumerationRetry<T>(operation: () => Promise<T>, opts?: {
+    maxAttempts?: number;
+    retryDelaysMs?: readonly number[];
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T>;
+/** Charge one path before retaining it or doing work derived from it. */
+export declare function consumeMetadataPath(budget: MetadataBudget, value: string, label: string): void;
+/** Validate an existing collection incrementally, without an intermediate map. */
+export declare function assertMetadataPathCollection(values: Iterable<string>, label: string, budget?: MetadataBudget): void;
+/** Validate object-backed path collections without allocating `items.map(...)`. */
+export declare function assertMetadataItemPathCollection<T>(items: Iterable<T>, pathOf: (item: T) => string, label: string, budget?: MetadataBudget): void;
+export interface BoundedDirectoryStat {
+    dev: string;
+    ino: string;
+    birthtimeNs: string;
+    canonicalPath: string;
+    size: bigint;
+    mtimeMs: number;
+    mtimeNs: string;
+    ctimeNs: string;
+    nlink: string;
+}
+/** Metadata captured in the same isolated enumeration request, when requested. */
+export declare function boundedDirectoryStat(entry: Dirent): BoundedDirectoryStat | undefined;
+/**
+ * Enumerate a directory in an isolated process group. The helper's absolute
+ * deadline is armed before its first target-filesystem access, so a blocked
+ * FUSE/network open, read, or close cannot retain a desktop lifecycle lock.
+ * Entries are streamed and charged in the desktop before being retained.
+ */
+export declare function readDirectoryBounded(dirPath: string, budget: MetadataBudget, label: string, relativePrefix?: string, opts?: {
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic target-filesystem stall seam. */
+    testHangStage?: 'open' | 'read' | 'stat' | 'close';
+    /** Capture lstat metadata inside the same deadline-bound worker request. */
+    includeStats?: boolean;
+    /** @internal deterministic seam after a missing component, before acknowledgement. */
+    beforeMissing?: () => Promise<void> | void;
+    /** @internal deterministic seam before final public-chain authentication. */
+    beforeCompletion?: () => Promise<void> | void;
+    /** Exact directory inode that must own the enumeration. */
+    expectedDirectory?: {
+        dev: string;
+        ino: string;
+        birthtimeNs?: string;
+        canonicalPath?: string;
+        size?: bigint;
+        mtimeNs?: string;
+        ctimeNs?: string;
+        nlink?: string;
+    };
+    /** Persisted root authority used to enter the complete relative chain. */
+    rootAuthority?: WorkspaceRootAuthority;
+    /** Directory path relative to `rootAuthority` (empty means the root). */
+    relativeDirectory?: string;
+}): Promise<Dirent[]>;

package/dist/local-executor/bounded-helper.d.ts

@@ -0,0 +1,22 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+/** Production ceiling for one helper protocol wait or helper subtree. */
+export declare const DEFAULT_HELPER_TIMEOUT_MS: number;
+export declare const MAX_HELPER_TIMEOUT_MS: number;
+/** Cleanup is itself bounded; callers must never wait forever for `close`. */
+export declare const DEFAULT_HELPER_TERMINATION_TIMEOUT_MS = 5000;
+/** Absolute deadline inherited by recursive helper descendants. */
+export declare const HELPER_DEADLINE_ENV = "CODEVIBE_HELPER_DEADLINE_AT_MS";
+export declare const HELPER_TIMEOUT_ENV = "CODEVIBE_HELPER_TIMEOUT_MS";
+export declare function resolveHelperTimeout(value: number | undefined): number;
+export declare function helperDeadlineEnv(timeoutMs: number): Record<string, string>;
+/** Spawn every top-level helper in its own POSIX process group. */
+export declare function spawnIsolatedHelper(command: string, args: readonly string[], options: SpawnOptions): ChildProcess;
+export declare function observeChildClose(child: ChildProcess): Promise<number | null>;
+export declare function withHelperDeadline<T>(work: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+/**
+ * Best-effort full-tree termination with a hard upper bound on cleanup wait.
+ * POSIX helpers are isolated process-group leaders. Windows uses taskkill's
+ * `/T` tree semantics and then a direct-kill fallback; neither path is awaited
+ * without a deadline.
+ */
+export declare function terminateHelperTree(child: ChildProcess | undefined, closed: Promise<unknown> | undefined, timeoutMs?: number): Promise<void>;

package/dist/local-executor/bounded-output.d.ts

@@ -0,0 +1,11 @@
+/** Maximum retained bytes per stdout/stderr stream; pipes are still fully drained. */
+export declare const MAX_RETAINED_PROCESS_OUTPUT_BYTES: number;
+export declare class BoundedOutputBuffer {
+    private readonly limit;
+    private chunks;
+    private bytes;
+    constructor(limit?: number);
+    push(value: Buffer | string): void;
+    toBuffer(): Buffer;
+    toString(): string;
+}

package/dist/local-executor/class-a-emit.d.ts

@@ -2,7 +2,7 @@ import type { AdapterProgressEnvelope } from '../adapter/progress';
 import { AuthorityRefusal, AuthorityRefusalCategory } from './authority';
 import { type DeviceSigningKey } from './class-a-sign';
 import { AgentKind, FailureClass, ProcessRole } from './types';
-export type ExecutionEventKind = 'PROCESS_SPAWNED' | 'TOOL_USE' | 'FILE_CHANGE' | 'VERIFICATION_RUN' | 'PROCESS_EXITED';
+export type ExecutionEventKind = 'PROCESS_SPAWNED' | 'TOOL_USE' | 'FILE_CHANGE' | 'VERIFICATION_RUN' | 'PROCESS_EXITED' | 'TRACK_PROGRESS';
 export type ClassAMessageType = 'EXECUTION_EVENT' | 'EXECUTOR_REFUSAL' | 'VERIFICATION_RESULT' | 'ADAPTER_PROGRESS';
 export interface ClassAEnvelope {
     messageVersion: 1;
@@ -51,6 +51,15 @@ export interface ProcessExitedPayload {
     exitCode: number;
     failureClass: FailureClass;
 }
+/** Team-child liveness fact; its hosted audit append renews the exact lease. */
+export interface TrackProgressPayload {
+    kind: 'TRACK_PROGRESS';
+    taskGroupId: string;
+    trackIndex: number;
+    dispatchGeneration: number;
+    phase: 'track_spawned' | 'lease_heartbeat';
+    sequence: number;
+}
 export interface ExecutorRefusalPayload {
     refusedMessageId: string;
     refusalCategory: AuthorityRefusalCategory;
@@ -124,6 +133,9 @@ export declare class ClassAEmitter {
         failureClass: FailureClass;
         occurredAt?: string;
     }): Promise<void>;
+    emitTrackProgress(ctx: ClassAEmitterContext, args: Omit<TrackProgressPayload, 'kind'> & {
+        occurredAt?: string;
+    }): Promise<void>;
     emitExecutorRefusal(ctx: ClassAEmitterContext, args: {
         refusal: AuthorityRefusal;
         refusedMessageId: string;

package/dist/local-executor/durable-directory.d.ts

@@ -0,0 +1,25 @@
+export interface DurableDirectoryIdentity {
+    canonicalPath: string;
+    dev: string;
+    ino: string;
+    birthtimeNs: string;
+    mtimeMs: number;
+    created: boolean;
+}
+/**
+ * Create/validate a directory tree and seal every acknowledged target with
+ * child-then-parent fsync inside a killable, deadline-bound helper.
+ */
+export declare function ensureDurableDirectoryTree(target: string, opts?: {
+    /** Existing durable ancestor; every controlled descendant is resealed on every retry. */
+    anchorPath?: string;
+    mode?: number;
+    enforceTargetMode?: boolean;
+    helperTimeoutMs?: number;
+    /** @internal deterministic durability failure seam. */
+    failDirectorySyncStage?: 'created-child' | 'created-parent' | 'target-child' | 'target-parent';
+    /** @internal deterministic target-filesystem stall seam. */
+    testHangStage?: 'anchor-open' | 'component-open' | 'mkdir' | 'created-child' | 'created-parent' | 'target-child' | 'target-parent';
+    /** @internal replace the live anchor after binding; proves cwd anchoring and final rejection. */
+    testSwapAnchorTo?: string;
+}): Promise<DurableDirectoryIdentity>;