praxis-agent 0.60.1 → 0.62.0

package/README.md

@@ -215,9 +215,16 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   tool, memory, first-turn, and resume behavior. Agent execution uses one
   durable lifecycle vocabulary with bounded cancellation and drain,
   continuation, notifications, and single-owner orphan recovery. Isolated
-  Workflow turns use ownership-recorded repo-local temporary worktrees and
-  retain dirty or committed results for inspection. Experimental
-  local Teams (`PRAXIS_ENABLE_TEAMS=true`) stay absent from ordinary startup by
+  Workflow and Agent turns use isolated repo-local worktrees with trusted
+  synchronous lifecycle hooks. Blocked creation rolls back safely; unchanged
+  worktrees are cleaned up, while failed, dirty, committed, or otherwise
+  unsafe worktrees retain evidence for inspection. Restore accepts only an
+  owned current or exact historical Agent path; invalid or unavailable
+  evidence safely falls back to the parent cwd. Managed worktrees expose
+  bounded five-state lifecycle diagnostics through `praxis doctor`, while
+  Team `status`, `logs`, and `attach` surface the same read-only lifecycle
+  evidence. Experimental local Teams (`PRAXIS_ENABLE_TEAMS=true`) stay absent
+  from ordinary startup by
   default and add durable task ownership plus one ordered mailbox with stable
   identities, fixed broadcast recipients, durable cursors, bounded retention,
   and bounded model-context projection. Teams are explicitly experimental and
@@ -233,7 +240,17 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   CLI also exposes `praxis team status`, `logs`, and `attach` in human or JSON
   form; durable-local attach does not require tmux. Native task, notification,
   context, and Team resume/inbox seams are implemented with fail-closed
-  validation for unsupported payloads.
+  validation for unsupported payloads. New write-capable Team generations use
+  repo-local durable worktrees under `.praxis/worktrees/team/<team-id>/<generation-hash>`
+  with exact ownership records, markers, branches, and execution tokens. Read-only
+  Team members continue to use the invocation checkout. Completion, failure,
+  cancellation, orphaning, stop, and persistence uncertainty retain writer
+  evidence and relinquish the active lease; only a durably persisted explicit
+  Lead `accepted` decision may release that exact generation, while rejection
+  retains it. The ownership-verified accepted path may explicitly dispose of
+  reviewed dirty or committed evidence; hook blocks and ownership uncertainty
+  fail closed. Exact historical global Team worktrees remain validation-only
+  compatibility and are never implicitly adopted.
 - **Native resource ecosystem** — shared Praxis instructions with recursive `@`
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and append-only `praxis.transcript` JSONL sessions under `~/.praxis`,

package/dist/application/agent-worktree-owner.d.ts

@@ -0,0 +1,12 @@
+export interface AgentWorktreeOwnerIdentity {
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly executionToken: string;
+}
+export declare function formatAgentWorktreeOwner(identity: AgentWorktreeOwnerIdentity): string;
+export declare function formatAgentWorktreeOwnerPrefix(identity: {
+    readonly sessionId: string;
+    readonly agentId: string;
+}): string;
+export declare function parseAgentWorktreeOwner(ownerId: string): AgentWorktreeOwnerIdentity | null;
+//# sourceMappingURL=agent-worktree-owner.d.ts.map

package/dist/application/agent-worktree-owner.js

@@ -0,0 +1,35 @@
+import { isSessionId } from '../core/session.js';
+const AGENT_ID_PATTERN = /^a(?:[A-Za-z0-9][A-Za-z0-9_-]{0,62}-)?[0-9a-f]{16}$/u;
+const EXECUTION_TOKEN_PATTERN = /^[A-Za-z0-9_-]{1,128}$/u;
+function isAgentWorktreeOwnerIdentity(value) {
+    return (isSessionId(value.sessionId) &&
+        AGENT_ID_PATTERN.test(value.agentId) &&
+        EXECUTION_TOKEN_PATTERN.test(value.executionToken));
+}
+function isAgentWorktreeIdentity(value) {
+    return isSessionId(value.sessionId) && AGENT_ID_PATTERN.test(value.agentId);
+}
+function assertAgentWorktreeOwnerIdentity(value) {
+    if (!isAgentWorktreeOwnerIdentity(value))
+        throw new Error('Invalid Agent worktree owner identity');
+}
+export function formatAgentWorktreeOwner(identity) {
+    assertAgentWorktreeOwnerIdentity(identity);
+    return `agent:${identity.sessionId}:${identity.agentId}:${identity.executionToken}`;
+}
+export function formatAgentWorktreeOwnerPrefix(identity) {
+    if (!isAgentWorktreeIdentity(identity))
+        throw new Error('Invalid Agent worktree owner identity');
+    return `agent:${identity.sessionId}:${identity.agentId}:`;
+}
+export function parseAgentWorktreeOwner(ownerId) {
+    const parts = ownerId.split(':');
+    if (parts.length !== 4 || parts[0] !== 'agent')
+        return null;
+    const sessionId = parts[1] ?? '';
+    const agentId = parts[2] ?? '';
+    const executionToken = parts[3] ?? '';
+    const identity = { sessionId, agentId, executionToken };
+    return isAgentWorktreeOwnerIdentity(identity) ? identity : null;
+}
+//# sourceMappingURL=agent-worktree-owner.js.map

package/dist/application/agent-worktree.d.ts

@@ -0,0 +1,19 @@
+import { type ManagedWorktree } from './managed-worktree.js';
+import { type ManagedWorktreeHookContext } from './managed-worktree-hooks.js';
+export declare function createAgentWorktree(options: {
+    cwd: string;
+    stateRoot: string;
+    sessionId: string;
+    agentId: string;
+    executionToken: string;
+    hookContext?: ManagedWorktreeHookContext;
+}): Promise<ManagedWorktree>;
+export declare function restoreAgentWorktree(options: {
+    cwd: string;
+    stateRoot: string;
+    sessionId: string;
+    agentId: string;
+    path: string;
+    hookContext?: ManagedWorktreeHookContext;
+}): Promise<ManagedWorktree>;
+//# sourceMappingURL=agent-worktree.d.ts.map

package/dist/application/agent-worktree.js

@@ -0,0 +1,96 @@
+import { execFile } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { createOwnedManagedWorktree, restoreManagedWorktree, restoreOwnedManagedWorktree, } from './managed-worktree.js';
+import { createManagedWorktreeHooks, } from './managed-worktree-hooks.js';
+import { resolveProjectIdentity } from '../platform/project-identity.js';
+import { formatAgentWorktreeOwner, formatAgentWorktreeOwnerPrefix, } from './agent-worktree-owner.js';
+const execFileAsync = promisify(execFile);
+function agentWorktreeDirectoryName(sessionId, agentId) {
+    return `${sessionId}-${agentId}`;
+}
+export async function createAgentWorktree(options) {
+    return createOwnedManagedWorktree({
+        cwd: options.cwd,
+        stateRoot: options.stateRoot,
+        directoryName: agentWorktreeDirectoryName(options.sessionId, options.agentId),
+        ownerId: formatAgentWorktreeOwner({
+            sessionId: options.sessionId,
+            agentId: options.agentId,
+            executionToken: options.executionToken,
+        }),
+        label: 'Agent',
+        kind: 'agent',
+        policy: 'ephemeral',
+        ...(options.hookContext
+            ? { hooks: createManagedWorktreeHooks(options.hookContext) }
+            : {}),
+    });
+}
+async function git(cwd, args) {
+    return (await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf8' })).stdout.trim();
+}
+async function assertLegacyPath(options) {
+    if (!isAbsolute(options.path) ||
+        options.path.includes('\0') ||
+        resolve(options.path) !== options.expectedPath) {
+        throw new Error('retained Agent worktree path is not the legacy path');
+    }
+    const entry = await lstat(options.path);
+    if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new Error('retained Agent worktree must be a real directory');
+    }
+    const canonicalPath = await realpath(options.path);
+    const repositoryRoot = await resolveProjectIdentity(options.cwd);
+    if (repositoryRoot !== (await resolveProjectIdentity(options.path))) {
+        throw new Error('retained Agent worktree repository identity does not match');
+    }
+    const registrations = await git(options.cwd, [
+        'worktree',
+        'list',
+        '--porcelain',
+        '-z',
+    ]);
+    const registered = registrations
+        .split('\0')
+        .filter((line) => line.startsWith('worktree '))
+        .map((line) => resolve(repositoryRoot, line.slice('worktree '.length)));
+    if (!registered.includes(options.path) &&
+        !registered.includes(canonicalPath)) {
+        throw new Error('retained Agent worktree is not registered');
+    }
+}
+export async function restoreAgentWorktree(options) {
+    if (!isAbsolute(options.path) || options.path.includes('\0')) {
+        throw new Error('retained Agent worktree path is invalid');
+    }
+    const managedPath = join(await resolveProjectIdentity(options.cwd), '.praxis', 'worktrees', 'agent', agentWorktreeDirectoryName(options.sessionId, options.agentId));
+    const path = resolve(options.path);
+    if (path === managedPath) {
+        return restoreOwnedManagedWorktree({
+            cwd: options.cwd,
+            stateRoot: options.stateRoot,
+            path,
+            directoryName: agentWorktreeDirectoryName(options.sessionId, options.agentId),
+            ownerPrefix: formatAgentWorktreeOwnerPrefix(options),
+            label: 'Agent',
+            kind: 'agent',
+            policy: 'ephemeral',
+            ...(options.hookContext
+                ? { hooks: createManagedWorktreeHooks(options.hookContext) }
+                : {}),
+        });
+    }
+    const legacyPath = join(resolve(options.stateRoot), 'agent-worktrees', agentWorktreeDirectoryName(options.sessionId, options.agentId));
+    if (path !== legacyPath) {
+        throw new Error('retained Agent worktree path is not an accepted path');
+    }
+    await assertLegacyPath({
+        cwd: options.cwd,
+        path,
+        expectedPath: legacyPath,
+    });
+    return restoreManagedWorktree({ cwd: options.cwd, path, label: 'Agent' });
+}
+//# sourceMappingURL=agent-worktree.js.map

package/dist/application/managed-worktree-hooks.d.ts

@@ -0,0 +1,11 @@
+import type { ClaudeHookRunner } from '../hooks/claude-hooks.js';
+import type { ManagedWorktreeHooks } from './managed-worktree.js';
+export interface ManagedWorktreeHookContext {
+    runner: ClaudeHookRunner;
+    sessionId: string;
+    transcriptPath: string;
+    permissionMode: string;
+    signal?: AbortSignal;
+}
+export declare function createManagedWorktreeHooks(context: ManagedWorktreeHookContext): ManagedWorktreeHooks;
+//# sourceMappingURL=managed-worktree-hooks.d.ts.map

package/dist/application/managed-worktree-hooks.js

@@ -0,0 +1,23 @@
+function lifecycleHookInput(input, context, event) {
+    const reason = 'reason' in input ? input.reason : undefined;
+    return {
+        session_id: context.sessionId,
+        transcript_path: context.transcriptPath,
+        cwd: input.worktreePath,
+        permission_mode: context.permissionMode,
+        hook_event_name: event,
+        worktree_path: input.worktreePath,
+        worktree_kind: input.worktreeKind,
+        worktree_id: input.worktreeId,
+        owner_id: input.ownerId,
+        base_commit: input.baseCommit,
+        ...(event === 'WorktreeRemove' && reason !== undefined ? { reason } : {}),
+    };
+}
+export function createManagedWorktreeHooks(context) {
+    return {
+        afterCreate: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeCreate'), input.worktreeKind, context.signal),
+        beforeRemove: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeRemove'), input.worktreeKind, context.signal),
+    };
+}
+//# sourceMappingURL=managed-worktree-hooks.js.map

package/dist/application/managed-worktree.d.ts

@@ -1,3 +1,4 @@
+import { type ManagedWorktreeRecord } from '../persistence/managed-worktree-store.js';
 export interface ManagedWorktreeCleanup {
     retained: boolean;
     reason?: string;
@@ -5,17 +6,104 @@ export interface ManagedWorktreeCleanup {
 export interface ManagedWorktree {
     cwd: string;
     cleanup(): Promise<ManagedWorktreeCleanup>;
+    retain(reason: string): Promise<ManagedWorktreeCleanup>;
+    release(): Promise<ManagedWorktreeCleanup>;
+}
+export interface ManagedWorktreeHookInput {
+    readonly worktreePath: string;
+    readonly worktreeKind: 'workflow' | 'agent' | 'team';
+    readonly worktreeId: string;
+    readonly ownerId: string;
+    readonly baseCommit: string;
+}
+export interface ManagedWorktreeRemoveHookInput extends ManagedWorktreeHookInput {
+    readonly reason: 'normal' | 'reconcile';
+}
+export interface ManagedWorktreeHookOutcome {
+    blockedReason?: string;
+}
+export interface ManagedWorktreeHooks {
+    afterCreate(input: ManagedWorktreeHookInput): Promise<ManagedWorktreeHookOutcome>;
+    beforeRemove(input: ManagedWorktreeRemoveHookInput): Promise<ManagedWorktreeHookOutcome>;
 }
 export interface OwnedManagedWorktreeOptions {
     cwd: string;
     stateRoot: string;
+    parentDirectoryName?: string;
     directoryName: string;
+    branch?: string;
     ownerId: string;
     label: 'Agent' | 'Workflow' | 'Team';
     kind: 'workflow' | 'agent' | 'team';
     policy: 'ephemeral' | 'durable';
+    hooks?: ManagedWorktreeHooks;
+}
+export type ManagedWorktreeReconciliationDisposition = 'released' | 'retained' | 'skipped' | 'invalid';
+export interface ManagedWorktreeReconciliationEntry {
+    recordPath: string;
+    worktreeId?: string;
+    disposition: ManagedWorktreeReconciliationDisposition;
+    reason: string;
 }
+export interface ManagedWorktreeReconciliationResult {
+    repositoryRoot: string;
+    inspected: number;
+    truncated: boolean;
+    entries: readonly ManagedWorktreeReconciliationEntry[];
+}
+export type ManagedWorktreeHealthStatus = 'active' | 'retained' | 'safely-releasable' | 'released' | 'unsafe';
+export interface ManagedWorktreeHealthEntry {
+    recordPath: string;
+    worktreeId: string | null;
+    kind: ManagedWorktreeRecord['kind'] | null;
+    policy: ManagedWorktreeRecord['policy'] | null;
+    recordState: ManagedWorktreeRecord['state'] | null;
+    worktreePath: string | null;
+    branch: string | null;
+    present: boolean | null;
+    status: ManagedWorktreeHealthStatus;
+    reason: string;
+}
+export interface ManagedWorktreeHealthReport {
+    repositoryRoot: string;
+    inspected: number;
+    truncated: boolean;
+    counts: {
+        active: number;
+        retained: number;
+        safelyReleasable: number;
+        released: number;
+        unsafe: number;
+    };
+    entries: readonly ManagedWorktreeHealthEntry[];
+}
+export declare function inspectManagedWorktreeHealth(options: {
+    cwd: string;
+    stateRoot: string;
+    limit?: number;
+}): Promise<ManagedWorktreeHealthReport>;
+export declare function reconcileManagedWorktrees(options: {
+    cwd: string;
+    stateRoot: string;
+    hooks?: ManagedWorktreeHooks;
+}): Promise<ManagedWorktreeReconciliationResult>;
 export declare function createOwnedManagedWorktree(options: OwnedManagedWorktreeOptions): Promise<ManagedWorktree>;
+export interface OwnedManagedWorktreeRestoreOptions {
+    cwd: string;
+    stateRoot: string;
+    path: string;
+    parentDirectoryName?: string;
+    directoryName: string;
+    ownerPrefix: string;
+    ownerId?: string;
+    branch?: string;
+    label: 'Agent' | 'Workflow' | 'Team';
+    kind: 'workflow' | 'agent' | 'team';
+    policy: 'ephemeral' | 'durable';
+    hooks?: ManagedWorktreeHooks;
+}
+/** Restore a checkout only when its complete managed ownership proof matches. */
+export declare function restoreOwnedManagedWorktree(options: OwnedManagedWorktreeRestoreOptions): Promise<ManagedWorktree>;
 export declare function createManagedWorktree(options: {
     cwd: string;
     parentDirectory: string;