@quantiya/codevibe-claude-plugin 2.0.7 → 2.0.8

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/advisory-attachment-journal.d.ts

@@ -0,0 +1,165 @@
+import { type AnchoredCommittedFile } from '../local-executor/anchored-fs';
+import { type ProcessIdentity } from '../local-executor/process-identity';
+import { type ProcessCleanupOwner } from '../local-executor/process-tree';
+import { type WorkspaceRootAuthority } from '../local-executor/workspace-authority';
+export declare function advisoryAttachmentJournalRoot(home?: string): string;
+export interface BatchRecordV1 {
+    version: 1;
+    kind: 'batch';
+    batchId: string;
+    sessionId: string;
+    workspaceKey: string;
+    owner: ProcessIdentity;
+    workspaceRoot: WorkspaceRootAuthority;
+    directory: WorkspaceRootAuthority;
+    createdAtMs: number;
+}
+interface AttachmentContentAuthority {
+    sha256: string;
+    size: number;
+    mode: number;
+}
+export interface AttachmentRecordV1 {
+    version: 1;
+    kind: 'attachment';
+    recordId: string;
+    batchId: string;
+    sessionId: string;
+    owner: ProcessIdentity;
+    workspaceRoot: WorkspaceRootAuthority;
+    directory: WorkspaceRootAuthority;
+    targetName: string;
+    content: AttachmentContentAuthority;
+    phase: 'pending' | 'committed';
+    file: AnchoredCommittedFile | null;
+    createdAtMs: number;
+}
+export interface AdvisoryProcessRecordV1 {
+    version: 1;
+    kind: 'process';
+    recordId: string;
+    batchId: string;
+    sessionId: string;
+    owner: ProcessIdentity;
+    workspaceRoot: WorkspaceRootAuthority;
+    processOwner: ProcessCleanupOwner;
+    createdAtMs: number;
+}
+export interface AdvisoryAttachmentBatchAuthority {
+    readonly value: BatchRecordV1;
+    readonly recordPath: string;
+    readonly recordIdentity: AnchoredCommittedFile;
+}
+export interface AdvisoryAttachmentPublicationAuthority {
+    readonly value: AttachmentRecordV1;
+    readonly recordPath: string;
+    readonly recordIdentity: AnchoredCommittedFile;
+}
+export interface AdvisoryProcessAuthority {
+    readonly value: AdvisoryProcessRecordV1;
+    readonly recordPath: string;
+    readonly recordIdentity: AnchoredCommittedFile;
+}
+export interface AdvisoryAttachmentRecoveryResult {
+    recoveredAttachments: number;
+    retiredBatches: number;
+    retainedLive: number;
+}
+export declare class AdvisoryAttachmentWorkspaceBlockedError extends Error {
+    constructor(message?: string);
+}
+export declare class AdvisoryAttachmentJournal {
+    private readonly sessionId;
+    private readonly rootPath;
+    private readonly anchorPath;
+    private readonly currentOwner;
+    private readonly ownerIsAlive;
+    private readonly retryProcessOwner;
+    private readonly mintId;
+    private readonly now;
+    private readonly retirementSettleMs;
+    private rootAuthority;
+    private readonly activeBatchIds;
+    constructor(opts: {
+        sessionId: string;
+        /** @internal isolated private root for deterministic tests. */
+        rootDir?: string;
+        /** @internal existing ancestor for the isolated private root. */
+        anchorPath?: string;
+        /** @internal deterministic OS-incarnation seam for recovery tests. */
+        currentProcessIdentityFn?: () => Promise<ProcessIdentity>;
+        /** @internal deterministic liveness seam for recovery tests. */
+        isProcessIdentityAliveFn?: (identity: ProcessIdentity) => Promise<boolean>;
+        /** @internal deterministic exact process-group recovery seam. */
+        retryProcessCleanupOwnerFn?: (owner: ProcessCleanupOwner) => Promise<void>;
+        /** @internal deterministic UUID seam for recovery/collision tests. */
+        newId?: () => string;
+        /** @internal deterministic timestamp seam for canonical-record tests. */
+        now?: () => number;
+        /** @internal shorten the transient helper-retirement observation window. */
+        retirementSettleMs?: number;
+    });
+    private openRoot;
+    private readRecord;
+    private readRetirementRecord;
+    private helperArtifactTarget;
+    private listRecords;
+    private writeNewRecord;
+    private replaceRecord;
+    private removeRecord;
+    private assertBatchToken;
+    private assertPublicationToken;
+    private assertProcessToken;
+    private recoverProcessRecord;
+    /**
+     * `anchoredRemoveFile` quarantines an exact file under a fresh private
+     * `.codevibe-retire-*` name before unlink. If the helper dies in that narrow
+     * interval, recover the tombstone by immutable inode/content authority rather
+     * than by a pathname capability that the helper deliberately never exposes.
+     */
+    private findRetiredImage;
+    private recoverAttachmentRecord;
+    recoverDeadOwners(): Promise<AdvisoryAttachmentRecoveryResult>;
+    assertWorkspaceSafe(workingDir: string): Promise<void>;
+    assertBatchOwnsWorkspace(batch: AdvisoryAttachmentBatchAuthority, workingDir: string): Promise<void>;
+    beginBatch(args: {
+        workspaceRoot: WorkspaceRootAuthority;
+        directory: WorkspaceRootAuthority;
+    }): Promise<AdvisoryAttachmentBatchAuthority>;
+    /**
+     * Bind one exact advisory process group to the image batch before the
+     * untrusted target receives its launch ACK. A separate record per panel cell
+     * avoids shared-record CAS races when several advisors start concurrently.
+     */
+    beginProcess(batch: AdvisoryAttachmentBatchAuthority, processOwner: ProcessCleanupOwner): Promise<AdvisoryProcessAuthority>;
+    /**
+     * Retire a process binding only after exact process-group absence is proven.
+     * The spawn layer already performs this proof before its retirement hook;
+     * repeating it here makes the journal API independently fail closed.
+     */
+    retireProcess(authority: AdvisoryProcessAuthority, processOwner: ProcessCleanupOwner): Promise<void>;
+    beginPublication(args: {
+        batch: AdvisoryAttachmentBatchAuthority;
+        extension: string;
+        bytes: Buffer;
+    }): Promise<AdvisoryAttachmentPublicationAuthority>;
+    commitPublication(authority: AdvisoryAttachmentPublicationAuthority, file: AnchoredCommittedFile): Promise<AdvisoryAttachmentPublicationAuthority>;
+    abortUnpublished(authority: AdvisoryAttachmentPublicationAuthority): Promise<void>;
+    cleanupPublication(authority: AdvisoryAttachmentPublicationAuthority): Promise<void>;
+    /**
+     * Resolve an ambiguous image/journal commit failure from the immutable
+     * pending authority. The record identity may legitimately have advanced to
+     * `committed` before the caller lost the acknowledgement, so this verifies
+     * the immutable batch/target/content tuple rather than requiring the stale
+     * record inode.
+     */
+    recoverPublication(authority: AdvisoryAttachmentPublicationAuthority): Promise<void>;
+    finishBatch(batch: AdvisoryAttachmentBatchAuthority): Promise<void>;
+    /**
+     * Final normal-exit audit. It retries only this journal instance's batches
+     * (or definitely-dead predecessors), then refuses successful retirement while
+     * any record for the session remains.
+     */
+    disposeSession(): Promise<void>;
+}
+export {};

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/attachments.d.ts

@@ -1,4 +1,7 @@
 import type { ImageAttachment } from './types';
+import { type AnchoredCommittedFile } from '../local-executor/anchored-fs';
+import { type WorkspaceRootAuthority } from '../local-executor/workspace-authority';
+import { AdvisoryAttachmentJournal, type AdvisoryAttachmentBatchAuthority, type AdvisoryAttachmentPublicationAuthority } from './advisory-attachment-journal';
 /** Per-file on-disk cap (§10.5). */
 export declare const MAX_IMAGE_BYTES: number;
 /** Max attachments on the FINAL accumulated+deduped task set (§5). */
@@ -67,75 +70,61 @@ export interface CopiedAttachment {
     mime: string;
 }
 /**
- * [#637 Stage-2 R6 HIGH] The pinned filesystem identity of the attachments dir
- * (`dev`+`ino` from the validation/creation-time lstat). `O_NOFOLLOW` guards
- * only the FINAL path component, so any op that RESOLVES THROUGH the dir
- * (tmp-file open, rename, unlink, rmdir) must re-verify the parent dir is
- * still the very same inode immediately beforehand — a concurrent swap of
- * `.codevibe-attachments` to a symlink would otherwise redirect writes or
- * deletions outside the repo.
+ * Exact filesystem authority retained from advisory staging through cleanup.
+ * Paths alone are never deletion authority.
  */
-export interface AttachmentsDirIdentity {
-    dev: number;
-    ino: number;
+export interface AdvisoryAttachmentCleanupAuthority {
+    /** Private durable owner; the shared exact ignore guard is persistent. */
+    journal: AdvisoryAttachmentJournal;
+    batch: AdvisoryAttachmentBatchAuthority;
+    /** Only exact turn-owned image publications. */
+    files: Array<{
+        identity: AnchoredCommittedFile;
+        publication: AdvisoryAttachmentPublicationAuthority;
+    }>;
 }
-/**
- * [R6 HIGH] Identity re-check immediately before a write/cleanup op that
- * resolves through the attachments dir: lstat (never follows), must be a REAL
- * directory with the SAME dev+ino as pinned at validation time. Any mismatch,
- * missing identity, or lstat failure → false (fail CLOSED). Node has no
- * openat-style fd-relative open/rename/unlink; the immediately-preceding
- * re-check is the accepted approximation (the residual window is the single
- * syscall gap).
- */
-export declare function verifyAttachmentsDirIdentity(dirPath: string, identity: AttachmentsDirIdentity | null): boolean;
 export interface PreparedAttachments {
     copiedAttachments: CopiedAttachment[];
     failedAttachments: ImageAttachment[];
     /** The brief with FAILED-copy refs rewritten to a neutral marker (no dangling ref). */
     roundBrief: string;
-    /**
-     * [#637 Stage-2 R5 LOW-3] True iff THIS call's OWN mkdir created the
-     * attachments dir (non-recursive — a dir raced into existence by another
-     * process signals EEXIST → false). The advisory caller gates its cleanup
-     * rmdir on this so it never removes a dir it did not create; a caller-side
-     * stat-before-await inference was racy.
-     */
-    createdAttachmentsDir: boolean;
-    /**
-     * [R6 HIGH] The pinned identity every copy was verified against — null when
-     * staging was refused or no directory could be established. Cleanup callers
-     * MUST pass this to `verifyAttachmentsDirIdentity` immediately before each
-     * unlink and the rmdir.
-     */
-    attachmentsDirIdentity: AttachmentsDirIdentity | null;
+    /** Present only for real-worktree advisory staging. */
+    advisoryCleanupAuthority: AdvisoryAttachmentCleanupAuthority | null;
 }
 /**
- * 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.
+ * Stage read-only brainstorm attachments in the user's real worktree.
  *
- * [#637] `destMode: 'real_worktree'` — the read-only advisory panel stages into
- * the user's REAL repo (no shadow). A pre-existing symlink / non-directory at
- * `.codevibe-attachments` there belongs to the USER, so the whole staging is
- * REFUSED (every attachment failed, refs neutralized; the advisory proceeds
- * text-only) instead of the shadow path's rm-and-recreate. Default `'shadow'`
- * keeps the replacement behavior — the shadow is disposable and the entry there
- * could only be implementor-planted.
+ * This path deliberately remains separate from implementor snapshot staging:
+ * user-owned conflicting entries are never removed, and the caller receives
+ * exact creation + inode identity so its per-turn cleanup cannot traverse a
+ * replacement symlink.
+ */
+export declare function prepareAttachmentsForAdvisoryWorktree(roundBrief: string, attachments: ImageAttachment[], workdir: string, journal: AdvisoryAttachmentJournal, opts?: {
+    /** @internal deterministic root-replacement seam. */
+    onRootCaptured?: (authority: WorkspaceRootAuthority) => Promise<void> | void;
+    /** @internal deterministic directory-replacement seam. */
+    onDirEnsured?: (authority: WorkspaceRootAuthority) => Promise<void> | void;
+    /** @internal deterministic pre-publication swap seam. */
+    beforeFileCommit?: (attachment: ImageAttachment, destination: string) => Promise<void> | void;
+}): Promise<PreparedAttachments>;
+/**
+ * Retire only files committed by one advisory staging call. Exact file,
+ * directory, and root identities are re-authenticated by anchored helpers;
+ * replacement entries are retained untouched.
+ */
+export declare function cleanupPreparedAdvisoryAttachments(prepared: PreparedAttachments, opts?: {
+    /** @internal deterministic exact-unlink race seam. */
+    beforeFileRemove?: (file: AnchoredCommittedFile, quarantinePath: string) => Promise<void> | void;
+}): Promise<void>;
+/**
+ * Per-round copy + failure-rewrite in ONE step (§7.3, rev-7). For each attachment,
+ * validate the captured snapshot authority, create its attachments directory
+ * through the anchored helper, and publish each bounded/re-sniffed image with
+ * an anchored atomic write. A failed copy rewrites that attachment's neutral
+ * reference to `[attached image skipped]`; this function never hard-blocks the
+ * task on attachment failure.
  */
-export declare function prepareAttachmentsForSpawn(roundBrief: string, attachments: ImageAttachment[], shadowDir: string, opts?: {
-    destMode?: 'shadow' | 'real_worktree';
-    /**
-     * Injectable test seam (deterministic swap-window tests, same idiom as
-     * `IngestOptions.newId`): runs between the dir-identity pin and the
-     * per-file copies — exactly the [R6 HIGH] race window.
-     */
-    onDirEnsured?: () => void;
-}): PreparedAttachments;
+export declare function prepareAttachmentsForSpawn(roundBrief: string, attachments: ImageAttachment[], shadowRootAuthority: WorkspaceRootAuthority): Promise<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>`);

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/bounded-shutdown.d.ts

@@ -7,6 +7,12 @@ export interface BoundedSharedShutdownOperationOptions {
     normalTimeoutMs: number;
     signalTimeoutMs: number;
     onTimeout?: (deadlineClass: ShutdownDeadlineClass, timeoutMs: number) => void;
+    /**
+     * Optionally turn a deadline into a caller-visible failure. Normal shutdown
+     * uses this to refuse a successful exit while cleanup authority is still
+     * unresolved; signal shutdown intentionally remains best-effort and bounded.
+     */
+    timeoutError?: (deadlineClass: ShutdownDeadlineClass, timeoutMs: number) => Error | undefined;
 }
 /**
  * Starts one shutdown operation and gives normal and signal callers one shared