vgxness 1.20.4 → 1.20.6

package/dist/permissions/policy-evaluator.js

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { classifyOperationRisk } from '../governance/risk-classifier.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
 import { commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
+import { evaluateExplicitRequestAuthorization } from './explicit-request-authorization.js';
 export { isRiskyPermissionCategory, permissionCategories, riskyPermissionCategories } from './schema.js';
 export const permissionDecisions = ['allow', 'ask', 'deny'];
 export const permissionModes = ['allow', 'audit', 'require-preflight', 'deny'];
@@ -21,8 +22,8 @@ export const defaultPermissionPolicy = {
         { category: 'network', decision: 'ask', reason: 'Network access is external and requires approval by default.' },
         { category: 'git', decision: 'ask', reason: 'Git operations can affect review state or remotes.' },
         { category: 'git-write', decision: 'ask', reason: 'Git writes can affect review state or remotes.' },
-        { category: 'memory', decision: 'ask', reason: 'Memory changes are durable and should be explicit.' },
-        { category: 'memory-write', decision: 'ask', reason: 'Memory writes are durable and should be explicit.' },
+        { category: 'memory', decision: 'ask', reason: 'Memory reads/writes are durable and audited; ordinary qualifying memory writes may proceed without duplicate confirmation.' },
+        { category: 'memory-write', decision: 'ask', reason: 'Memory writes are durable and audited; ordinary qualifying memory writes may proceed without duplicate confirmation.' },
         { category: 'external-directory', decision: 'deny', reason: 'External directory access is denied unless a future sandbox grants it explicitly.' },
         { category: 'provider-tool', decision: 'ask', reason: 'Provider-specific tools stay opaque and require approval by default.' },
         { category: 'secrets', decision: 'deny', reason: 'Secret access is privileged and denied by default.' },
@@ -41,8 +42,8 @@ const planningPhaseModes = {
     network: 'require-preflight',
     git: 'require-preflight',
     'git-write': 'require-preflight',
-    memory: 'require-preflight',
-    'memory-write': 'require-preflight',
+    memory: 'audit',
+    'memory-write': 'audit',
     'external-directory': 'deny',
     'provider-tool': 'audit',
     secrets: 'deny',
@@ -69,7 +70,14 @@ export const sddPhasePermissionMatrix = Object.fromEntries(sddPhases.map((phase)
     if (phase === 'archive')
         return [
             phase,
-            { ...verifyPhaseModes, git: 'require-preflight', 'git-write': 'require-preflight', memory: 'require-preflight', 'memory-write': 'require-preflight' },
+            {
+                ...verifyPhaseModes,
+                edit: 'require-preflight',
+                git: 'require-preflight',
+                'git-write': 'require-preflight',
+                memory: 'audit',
+                'memory-write': 'audit',
+            },
         ];
     return [phase, planningPhaseModes];
 }));
@@ -85,30 +93,30 @@ const filesystemCategories = new Set([
 export function evaluatePermission(request, policy = defaultPermissionPolicy) {
     const risk = classifyOperationRisk(request);
     if (request.category === 'secrets')
-        return result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk), risk);
     if (request.category === 'external-directory') {
-        return result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk), risk);
     }
     const hardRisk = hardRiskDecision(request, risk);
     if (hardRisk !== undefined)
-        return hardRisk;
+        return withExplicitRequestAuthorization(request, hardRisk, risk);
     const workspaceEscape = workspaceEscapeDecision(request);
     if (workspaceEscape !== undefined)
-        return workspaceEscape;
+        return withExplicitRequestAuthorization(request, workspaceEscape, risk);
     const verifyAllowlistedCommand = verifyAllowlistedCommandDecision(request, risk);
     if (verifyAllowlistedCommand !== undefined)
         return verifyAllowlistedCommand;
     const sddPhaseDecision = phaseMatrixDecision(request);
     if (sddPhaseDecision !== undefined && sddPhaseDecision.mode !== 'allow' && sddPhaseDecision.mode !== 'audit')
-        return sddPhaseDecision;
+        return withExplicitRequestAuthorization(request, sddPhaseDecision, risk);
     const explicitValidation = explicitValidationDecision(request, risk);
     if (explicitValidation !== undefined)
-        return explicitValidation;
+        return withExplicitRequestAuthorization(request, explicitValidation, risk);
     if (sddPhaseDecision !== undefined)
         return sddPhaseDecision;
     const boundary = workspaceBoundaryDecision(request);
     if (boundary !== undefined)
-        return boundary;
+        return withExplicitRequestAuthorization(request, boundary, risk);
     const agentDecision = request.agent?.permissions[request.category];
     const baseRule = policy.rules.find((rule) => rule.category === request.category);
     const baseDecision = agentDecision ?? baseRule?.decision ?? 'ask';
@@ -118,7 +126,7 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
         : (baseRule?.reason ?? `No explicit rule exists for ${request.category}; ask by default.`);
     const flagRisk = riskDecision(request);
     if (flagRisk !== undefined && isLessRestrictive(baseDecision, flagRisk.decision)) {
-        return result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk), risk);
     }
     if (risk.defaultDecision === 'audit' && baseDecision !== 'deny') {
         return result(request, 'allow', risk.reasonCodes.includes('provider_readonly_audit') ? 'provider_readonly_audit' : risk.reasonCodes.includes('allowlisted_verification') ? 'allowlisted_command' : baseReason, baseMessage, {
@@ -127,7 +135,39 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
             warnings: risk.reasonCodes.includes('provider_readonly_audit') ? ['provider-readonly-audit-only'] : ['audit-only'],
         }, risk);
     }
-    return result(request, baseDecision, baseReason, baseMessage, {}, risk);
+    return withExplicitRequestAuthorization(request, result(request, baseDecision, baseReason, baseMessage, {}, risk), risk);
+}
+function withExplicitRequestAuthorization(request, decision, risk) {
+    if (request.explicitRequest === undefined)
+        return decision;
+    const explicit = evaluateExplicitRequestAuthorization({ request, risk, evaluatedAt: new Date().toISOString() });
+    if (decision.decision !== 'ask') {
+        return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
+    }
+    if (explicit.decision === 'allow') {
+        return {
+            ...decision,
+            decision: 'allow',
+            reason: 'explicit_request_authorization',
+            message: 'Explicit human request authorizes this exact one-off operation.',
+            explicitRequestAudit: explicit.audit,
+            authorizationMode: 'explicit-request',
+            auditEvidence: [...(decision.auditEvidence ?? []), 'explicitRequest:exact-match'],
+        };
+    }
+    if (explicit.decision === 'deny') {
+        return {
+            ...decision,
+            decision: 'deny',
+            reason: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required') ? 'sdd_phase_policy' : 'risk_tier_policy',
+            message: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required')
+                ? 'SDD artifact acceptance is human-only and cannot be inferred from explicit-request preflight.'
+                : 'Explicit request contains a hard-stop condition and cannot authorize this operation.',
+            explicitRequestAudit: explicit.audit,
+            auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`],
+        };
+    }
+    return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
 }
 export function isPathInsideWorkspace(workspaceRoot, targetPath) {
     const root = resolve(workspaceRoot);

package/dist/runs/execution-planning.js

@@ -1,178 +1 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { recommendWorkspaceStrategy } from '../workspace-strategy/index.js';
-import { planWorktreeSandbox } from './sandbox-worktree-planning.js';
-const filesystemCategories = new Set(['read', 'edit', 'external-directory']);
-export function planExecutionIsolation(input) {
-    const { operation, decision } = input;
-    const strategy = selectStrategy(operation, decision);
-    const sandbox = worktreeSandboxPlan(operation, strategy, input.gitBoundaryInspector);
-    const realpathHardeningRequired = requiresRealpathHardening(operation);
-    const requiredApprovals = approvalRequirements(operation, decision);
-    const requiredConditions = conditionRequirements(operation, decision, realpathHardeningRequired, sandbox);
-    const limitations = planLimitations(operation, decision, strategy, sandbox);
-    return {
-        strategy,
-        pathConstraints: pathConstraints(operation),
-        ...(sandbox === undefined ? {} : { sandbox }),
-        realpathHardeningRequired,
-        requiredApprovals,
-        requiredConditions,
-        limitations,
-        executable: decision.decision === 'allow' && sandbox?.decision !== 'rejected',
-        executesProvider: false,
-        createsWorktree: false,
-    };
-}
-export function recommendWorkspaceStrategyForExecution(input) {
-    return recommendWorkspaceStrategy(workspaceStrategyInputForExecution(input));
-}
-export function workspaceStrategyInputForExecution(input) {
-    const categories = workspaceStrategyCategories(input.operation, input.decision);
-    const mutationSignal = hasWorkspaceMutationSignal(input.operation, categories);
-    return {
-        categories,
-        intentSignals: workspaceStrategyIntentSignals(input.operation, input.decision),
-        risk: workspaceStrategyRisk(input.decision),
-        readOnly: isReadOnlyWorkspaceOperation(input.operation, input.decision),
-        expectedWrites: mutationSignal,
-        mutatesRepository: mutationSignal,
-        destructive: input.operation.destructive === true,
-        external: input.operation.external === true || input.operation.category === 'external-directory',
-        privileged: input.operation.privileged === true,
-        ambiguous: input.operation.ambiguous === true,
-        changeSize: workspaceStrategyChangeSize(input.decision),
-        ...(mutationSignal ? { workspace: { checkout: 'unknown' } } : {}),
-    };
-}
-function selectStrategy(operation, decision) {
-    if (operation.sandboxStrategy === 'worktree')
-        return 'worktree';
-    if (decision.decision === 'deny') {
-        return operation.category === 'external-directory' || operation.external === true ? 'process-sandbox' : 'workspace';
-    }
-    if (operation.category === 'shell' || operation.category === 'network' || operation.category === 'provider-tool' || operation.privileged === true) {
-        return 'process-sandbox';
-    }
-    if (operation.category === 'edit' || operation.category === 'git' || operation.destructive === true) {
-        return 'worktree';
-    }
-    return 'workspace';
-}
-function pathConstraints(operation) {
-    return {
-        ...(operation.workspaceRoot === undefined ? {} : { workspaceRoot: operation.workspaceRoot }),
-        ...(operation.targetPath === undefined ? {} : { targetPath: operation.targetPath }),
-        enforceWorkspaceBoundary: operation.category !== 'external-directory',
-        allowExternalPaths: false,
-    };
-}
-function requiresRealpathHardening(operation) {
-    return filesystemCategories.has(operation.category) || operation.workspaceRoot !== undefined || operation.targetPath !== undefined;
-}
-function approvalRequirements(operation, decision) {
-    const approvals = [];
-    if (decision.decision === 'ask')
-        approvals.push(`human-approval:${decision.reason}`);
-    if (operation.destructive === true)
-        approvals.push('destructive-operation-approval');
-    if (operation.external === true || operation.category === 'external-directory')
-        approvals.push('external-access-approval');
-    if (operation.privileged === true)
-        approvals.push('privileged-operation-approval');
-    if (operation.ambiguous === true)
-        approvals.push('clarify-ambiguous-operation');
-    return [...new Set(approvals)];
-}
-function conditionRequirements(operation, decision, realpathHardeningRequired, sandbox) {
-    const conditions = ['permission-decision-recorded'];
-    if (decision.decision === 'deny')
-        conditions.push('blocked-by-policy-before-execution');
-    if (sandbox?.decision === 'rejected')
-        conditions.push(`blocked-by-sandbox-planning:${sandbox.reason ?? 'unknown'}`);
-    if (decision.decision === 'ask')
-        conditions.push('approved-before-execution');
-    if (realpathHardeningRequired)
-        conditions.push('resolve-realpath-and-recheck-workspace-boundary-before-execution');
-    if (operation.category === 'edit' || operation.category === 'git' || operation.destructive === true)
-        conditions.push('isolated-worktree-or-equivalent-before-mutation');
-    if (operation.category === 'shell' || operation.category === 'network' || operation.category === 'provider-tool')
-        conditions.push('sandboxed-process-or-equivalent-before-provider-execution');
-    return conditions;
-}
-function planLimitations(operation, decision, strategy, sandbox) {
-    const limitations = ['planning-only: this preflight records an execution plan only; no command, provider tool, worktree, sandbox, directory, or filesystem mutation was performed'];
-    if (strategy === 'worktree')
-        limitations.push('worktree is only the planned isolation target; no worktree was created and mutations still require a separate executor or manual worktree');
-    if (strategy === 'process-sandbox')
-        limitations.push('process-sandbox is only the planned isolation target; no sandbox was launched and execution still requires a separate executor');
-    if (decision.decision === 'deny')
-        limitations.push(`permission policy denies execution: ${decision.reason}`);
-    if (sandbox?.decision === 'rejected')
-        limitations.push(`sandbox planning rejects execution: ${sandbox.audit.validationSummary}`);
-    if (operation.category === 'external-directory')
-        limitations.push('external directory execution remains denied by default even when a stronger future sandbox is selected');
-    return limitations;
-}
-function worktreeSandboxPlan(operation, strategy, gitBoundaryInspector) {
-    if (strategy !== 'worktree')
-        return undefined;
-    if (operation.workspaceRoot === undefined || operation.targetPath === undefined)
-        return undefined;
-    return planWorktreeSandbox({
-        workspaceRoot: operation.workspaceRoot,
-        targetPath: operation.targetPath,
-        gitBoundaryInspector: gitBoundaryInspector ?? defaultGitBoundaryInspector,
-    });
-}
-const defaultGitBoundaryInspector = ({ workspaceRoot }) => {
-    if (existsSync(join(workspaceRoot, '.git'))) {
-        return { status: 'compatible', reason: 'workspace git metadata is present' };
-    }
-    return { status: 'compatible', reason: 'workspace has no git metadata to conflict with a planned worktree boundary' };
-};
-function workspaceStrategyCategories(operation, decision) {
-    const categories = [operation.category];
-    if (decision.riskReasonCodes?.includes('git_write') === true && !categories.includes('git-write'))
-        categories.push('git-write');
-    return categories;
-}
-function workspaceStrategyIntentSignals(operation, decision) {
-    return [
-        `permission:${decision.reason}`,
-        ...(decision.riskReasonCodes ?? []).map((code) => `risk:${code}`),
-        ...(operation.workflow === undefined ? [] : [`workflow:${operation.workflow}`]),
-        ...(operation.phase === undefined ? [] : [`phase:${operation.phase}`]),
-    ];
-}
-function workspaceStrategyRisk(decision) {
-    if (decision.riskTier === 0)
-        return 'none';
-    if (decision.riskTier === 1)
-        return 'low';
-    if (decision.riskTier === 2)
-        return 'medium';
-    if (decision.riskTier === 3)
-        return 'high';
-    if (decision.riskTier === 4)
-        return 'critical';
-    return 'unknown';
-}
-function workspaceStrategyChangeSize(decision) {
-    if (decision.riskReasonCodes?.some((code) => code === 'architecture_change' || code === 'cross_surface_change' || code === 'governance_change') === true)
-        return 'large';
-    if (decision.riskTier === 2)
-        return 'medium';
-    if (decision.riskTier === 1)
-        return 'small';
-    return 'unknown';
-}
-function isReadOnlyWorkspaceOperation(operation, decision) {
-    return decision.riskTier === 0 || operation.category === 'read' || (operation.category === 'git' && decision.riskReasonCodes?.includes('git_write') !== true);
-}
-function hasWorkspaceMutationSignal(operation, categories) {
-    if (operation.destructive === true || operation.privileged === true || operation.external === true || operation.ambiguous === true)
-        return true;
-    return categories.some((category) => workspaceMutationCategories.has(category));
-}
-const workspaceMutationCategories = new Set(['edit', 'implementation-edit', 'spec-write', 'design-write', 'task-write', 'git-write']);
+export * from '../application/runs/execution-planning.js';

package/dist/runs/operation-execution.js

@@ -1 +1 @@
-export {};
+export * from '../application/runs/operation-execution.js';

package/dist/runs/operation-retry.js

@@ -1,129 +1 @@
-const defaultRetryPolicy = { mode: 'never' };
-const operationRetryPolicyModes = [
-    'never',
-    'after-abandoned',
-    'after-failure',
-    'after-failure-or-abandoned',
-];
-const allowedRetryableStatuses = ['failed', 'abandoned'];
-export function defaultOperationRetryPolicy() {
-    return defaultRetryPolicy;
-}
-export function parseOperationRetryPolicy(input) {
-    if (input === undefined) {
-        return { ok: true, policy: defaultRetryPolicy };
-    }
-    if (!isRecord(input) || Array.isArray(input)) {
-        return { ok: false, errors: ['Retry policy must be an object'] };
-    }
-    const allowedKeys = new Set(['mode', 'retryableStatuses']);
-    const unknownKeys = Object.keys(input).filter((key) => !allowedKeys.has(key));
-    const errors = unknownKeys.map((key) => `Unknown retry policy field: ${key}`);
-    const mode = input.mode;
-    if (!isOperationRetryPolicyMode(mode)) {
-        errors.push('Retry policy mode must be one of: never, after-abandoned, after-failure, after-failure-or-abandoned');
-    }
-    if ('retryableStatuses' in input) {
-        const retryableStatuses = input.retryableStatuses;
-        if (!Array.isArray(retryableStatuses)) {
-            errors.push('Retry policy retryableStatuses must be an array');
-        }
-        else {
-            const invalidStatuses = retryableStatuses.filter((status) => !isAllowedRetryableStatus(status));
-            if (invalidStatuses.length > 0) {
-                errors.push(`Retry policy retryableStatuses contains invalid retryable status: ${invalidStatuses.map(String).join(', ')}`);
-            }
-            if (new Set(retryableStatuses).size !== retryableStatuses.length) {
-                errors.push('Retry policy retryableStatuses must not contain duplicates');
-            }
-            if (isOperationRetryPolicyMode(mode) && invalidStatuses.length === 0) {
-                const expectedStatuses = retryableStatusesFor({ mode });
-                if (!sameStatuses(retryableStatuses, expectedStatuses)) {
-                    errors.push(`Retry policy retryableStatuses must match mode ${mode}: ${expectedStatuses.length === 0 ? '[]' : expectedStatuses.join(', ')}`);
-                }
-            }
-        }
-    }
-    if (errors.length > 0 || !isOperationRetryPolicyMode(mode)) {
-        return { ok: false, errors };
-    }
-    return { ok: true, policy: { mode } };
-}
-export function evaluateOperationRetry(input) {
-    const policy = input.policy ?? defaultRetryPolicy;
-    const retryableStatuses = retryableStatusesFor(policy);
-    const attempts = [...input.attempts].sort(compareAttempts);
-    const activeAttempt = attempts.find((attempt) => attempt.status === 'reserved');
-    if (activeAttempt !== undefined) {
-        const latestAttempt = attempts.at(-1);
-        return {
-            allowed: false,
-            policy,
-            reasonCode: 'active_attempt_reserved',
-            reason: `Retry blocked because attempt ${activeAttempt.id} is still reserved`,
-            evaluatedAttemptCount: attempts.length,
-            retryableStatuses,
-            activeAttempt,
-            ...(latestAttempt === undefined ? {} : { latestAttempt }),
-        };
-    }
-    const latestAttempt = attempts.at(-1);
-    if (latestAttempt === undefined) {
-        return {
-            allowed: true,
-            policy,
-            reasonCode: 'initial_attempt_allowed',
-            reason: 'No previous operation attempt exists for this approval',
-            evaluatedAttemptCount: 0,
-            retryableStatuses,
-        };
-    }
-    if (latestAttempt.status === 'succeeded') {
-        return block(policy, retryableStatuses, attempts.length, latestAttempt, 'already_succeeded', `Retry blocked because latest attempt ${latestAttempt.id} already succeeded`);
-    }
-    if (policy.mode === 'never') {
-        return block(policy, retryableStatuses, attempts.length, latestAttempt, 'retry_disabled', `Retry blocked by policy never after ${latestAttempt.status}`);
-    }
-    if (retryableStatuses.includes(latestAttempt.status)) {
-        return {
-            allowed: true,
-            policy,
-            reasonCode: 'status_allowed_by_policy',
-            reason: `Retry allowed by policy ${policy.mode} after ${latestAttempt.status}`,
-            evaluatedAttemptCount: attempts.length,
-            retryableStatuses,
-            latestAttempt,
-        };
-    }
-    return block(policy, retryableStatuses, attempts.length, latestAttempt, 'status_not_allowed_by_policy', `Retry blocked by policy ${policy.mode} after ${latestAttempt.status}`);
-}
-function block(policy, retryableStatuses, evaluatedAttemptCount, latestAttempt, reasonCode, reason) {
-    return { allowed: false, policy, reasonCode, reason, evaluatedAttemptCount, retryableStatuses, latestAttempt };
-}
-function retryableStatusesFor(policy) {
-    switch (policy.mode) {
-        case 'after-abandoned':
-            return ['abandoned'];
-        case 'after-failure':
-            return ['failed'];
-        case 'after-failure-or-abandoned':
-            return ['failed', 'abandoned'];
-        case 'never':
-            return [];
-    }
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function isOperationRetryPolicyMode(value) {
-    return typeof value === 'string' && operationRetryPolicyModes.includes(value);
-}
-function isAllowedRetryableStatus(value) {
-    return typeof value === 'string' && allowedRetryableStatuses.includes(value);
-}
-function sameStatuses(actual, expected) {
-    return actual.length === expected.length && actual.every((status) => expected.includes(status));
-}
-function compareAttempts(a, b) {
-    return a.attemptSequence - b.attemptSequence || a.reservedAt.localeCompare(b.reservedAt) || a.id.localeCompare(b.id);
-}
+export * from '../application/runs/operation-retry.js';