@principles/pd-cli 1.113.0 → 1.114.0

package/src/commands/runtime-activation.ts

@@ -4,8 +4,12 @@ import {
   ActivationDispatcher,
   PromptWriter,
   DeferArchiveWriter,
+  RuleHostWriter,
+  createProductionGateDeps,
   SqliteActivationStateStore,
   SqliteApprovalQueueStore,
+  SqlitePIArtifactStore,
+  isArtifactRevisionOf,
 } from '@principles/core/runtime-v2';
 import type { ActivationDecision, PIArtifactSnapshot, RolloutActivationDecision } from '@principles/core/runtime-v2';
 import type { PIArtifactRecord } from '@principles/core/runtime-v2';
@@ -146,10 +150,19 @@ export async function handleRuntimeActivationDispatch(opts: ActivationDispatchOp
 
     const activationStateStore = new SqliteActivationStateStore(stateManager.connection);
     const approvalQueueStore = new SqliteApprovalQueueStore(stateManager.connection);
+    // Wire all three MVP-Core writers, including RuleHostWriter for code_tool_hook.
+    // PRI-408: fixes P0 breakpoint where code_tool_hook channel could not activate.
     const dispatcher = new ActivationDispatcher(
       artifactReadModel,
       activationStateStore,
-      { writers: [new PromptWriter(), new DeferArchiveWriter()], approvalQueueStore },
+      {
+        writers: [
+          new PromptWriter(),
+          new RuleHostWriter({ gateDeps: createProductionGateDeps() }),
+          new DeferArchiveWriter(),
+        ],
+        approvalQueueStore,
+      },
     );
 
     const result = await dispatcher.dispatch({
@@ -174,3 +187,448 @@ export async function handleRuntimeActivationDispatch(opts: ActivationDispatchOp
     await stateManager.close();
   }
 }
+
+// ── Deactivate Command (PRI-408 Contract E) ─────────────────────────────────
+
+interface ActivationDeactivateOptions {
+  workspace?: string;
+  activationId?: string;
+  json?: boolean;
+}
+
+export interface DeactivateResult {
+  ok: boolean;
+  activationId: string;
+  deactivatedAt?: string;
+  reason?: string;
+  nextAction?: string;
+}
+
+export async function handleRuntimeActivationDeactivate(opts: ActivationDeactivateOptions): Promise<void> {
+  if (!opts.activationId) {
+    const result: DeactivateResult = {
+      ok: false,
+      activationId: '',
+      reason: 'activation_id_required',
+      nextAction: 'Provide --activation-id <id> from `pd runtime activation list`',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: --activation-id is required`);
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+
+  try {
+    await stateManager.initialize();
+    const activationStateStore = new SqliteActivationStateStore(stateManager.connection);
+    const deactivatedAt = new Date().toISOString();
+
+    // Idempotent deactivate: returns false if already deactivated or not found.
+    // Both cases are safe to call repeatedly (Contract E: rollback must be idempotent).
+    const success = await activationStateStore.deactivateActivation(opts.activationId, deactivatedAt);
+
+    const result: DeactivateResult = success
+      ? { ok: true, activationId: opts.activationId, deactivatedAt }
+      : {
+          ok: false,
+          activationId: opts.activationId,
+          reason: 'not_found_or_already_deactivated',
+          nextAction: 'Check activation ID with `pd runtime activation list`, or it may already be deactivated',
+        };
+
+    if (opts.json) {
+      // Strict JSON mode: exactly one parseable JSON object on stdout
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (success) {
+        console.log(`Deactivated: ${opts.activationId}`);
+        console.log(`  deactivatedAt: ${deactivatedAt}`);
+      } else {
+        console.log(`Not deactivated: ${opts.activationId}`);
+        console.log(`  reason: ${result.reason}`);
+        console.log(`  nextAction: ${result.nextAction}`);
+      }
+    }
+
+    if (!success) {
+      process.exitCode = 1;
+    }
+  } catch (err: unknown) {
+    // P2 #5: initialize/DB exceptions must not break --json contract.
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const result: DeactivateResult = {
+      ok: false,
+      activationId: opts.activationId,
+      reason: `initialize_failed: ${errMsg}`,
+      nextAction: 'Check workspace directory and DB integrity. Try `pd runtime diagnostics`.',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.reason}`);
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    await stateManager.close();
+  }
+}
+
+// ── List Activations Command (PRI-408 Contract D — observability) ────────────
+
+interface ActivationListOptions {
+  workspace?: string;
+  channel?: string;
+  includeDeactivated?: boolean;
+  json?: boolean;
+}
+
+export async function handleRuntimeActivationList(opts: ActivationListOptions): Promise<void> {
+  // P2 #5 fix: fail loud on invalid channel instead of silently listing all.
+  const VALID_CHANNELS = new Set(['prompt', 'code_tool_hook', undefined]);
+  if (opts.channel !== undefined && !VALID_CHANNELS.has(opts.channel)) {
+    const result = {
+      ok: false,
+      reason: `invalid_channel: ${opts.channel}`,
+      nextAction: 'Use one of: prompt, code_tool_hook, or omit --channel to list all',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: invalid channel "${opts.channel}"`);
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+
+  try {
+    await stateManager.initialize();
+    const activationStateStore = new SqliteActivationStateStore(stateManager.connection);
+
+    // P2 #5 fix: pass includeDeactivated to the store so channel-specific queries
+    // also return deactivated records when requested. Previously the SQL hardcoded
+    // `WHERE deactivated_at IS NULL`, making --include-deactivated a no-op for
+    // channel-filtered queries.
+    let records;
+    if (opts.channel === 'prompt') {
+      records = await activationStateStore.listPromptActivations(opts.includeDeactivated ?? false);
+    } else if (opts.channel === 'code_tool_hook') {
+      records = await activationStateStore.listCodeToolHookActivations(opts.includeDeactivated ?? false);
+    } else {
+      records = await activationStateStore.listAllActivations();
+    }
+
+    // For listAllActivations, still apply the includeDeactivated filter at the
+    // caller level since listAllActivations() does not take the parameter.
+    const filtered = opts.includeDeactivated
+      ? records
+      : records.filter(r => r.deactivatedAt === null);
+
+    if (opts.json) {
+      // Strict JSON mode: exactly one parseable JSON object on stdout
+      console.log(JSON.stringify({ activations: filtered }, null, 2));
+    } else {
+      if (filtered.length === 0) {
+        console.log('No active activations found.');
+      } else {
+        for (const r of filtered) {
+          const status = r.deactivatedAt ? `[DEACTIVATED ${r.deactivatedAt}]` : '[ACTIVE]';
+          console.log(`${status} ${r.activationId}`);
+          console.log(`  artifactId: ${r.artifactId}`);
+          console.log(`  channel: ${r.channel}`);
+          console.log(`  action: ${r.action}`);
+          console.log(`  targetRef: ${r.targetRef}`);
+          console.log(`  activatedAt: ${r.activatedAt}`);
+          console.log('');
+        }
+      }
+    }
+  } catch (err: unknown) {
+    // P2 #5: initialize/DB exceptions must not break --json contract.
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const result = {
+      ok: false,
+      reason: `initialize_failed: ${errMsg}`,
+      nextAction: 'Check workspace directory and DB integrity. Try `pd runtime diagnostics`.',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.reason}`);
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    await stateManager.close();
+  }
+}
+
+// ── Edit Pending Approval Command (P1 #2 fix — Owner edit entry point) ──────
+
+interface ActivationEditOptions {
+  workspace?: string;
+  approvalId?: string;
+  newArtifactId?: string;
+  editReason?: string;
+  json?: boolean;
+}
+
+export interface EditApprovalResult {
+  ok: boolean;
+  approvalId?: string;
+  newArtifactId?: string;
+  previousArtifactId?: string;
+  editedAt?: string;
+  reason?: string;
+  nextAction?: string;
+}
+
+export async function handleRuntimeActivationEdit(opts: ActivationEditOptions): Promise<void> {
+  if (!opts.approvalId) {
+    const result: EditApprovalResult = {
+      ok: false,
+      reason: 'approval_id_required',
+      nextAction: 'Provide --approval-id <id> from Console approvals page',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error('Error: --approval-id is required');
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!opts.newArtifactId) {
+    const result: EditApprovalResult = {
+      ok: false,
+      reason: 'new_artifact_id_required',
+      nextAction: 'Create a new artifact first (e.g. via pd candidate intake), then pass its ID with --new-artifact-id',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error('Error: --new-artifact-id is required');
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!opts.editReason) {
+    const result: EditApprovalResult = {
+      ok: false,
+      reason: 'edit_reason_required',
+      nextAction: 'Provide --edit-reason explaining why the artifact is being revised',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error('Error: --edit-reason is required');
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+
+  try {
+    await stateManager.initialize();
+    const approvalStore = new SqliteApprovalQueueStore(stateManager.connection);
+    const artifactStore = new SqlitePIArtifactStore(stateManager.connection);
+    const now = new Date().toISOString();
+
+    // P1 #2: validate the new artifact before swapping the approval pointer.
+    // The new artifact must exist, be validated, and have lineage consistent
+    // with the original approval's artifact (same sourceTaskId).
+    const existingApproval = await approvalStore.getById(opts.approvalId);
+    if (!existingApproval) {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: 'not_found',
+        nextAction: 'Check the approval ID on Console approvals page',
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      await stateManager.close();
+      return;
+    }
+    if (existingApproval.status !== 'pending') {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: 'already_decided',
+        nextAction: `Approval is already decided (status: ${existingApproval.status}). Only pending approvals can be edited.`,
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      await stateManager.close();
+      return;
+    }
+
+    const newArtifact = await artifactStore.getArtifactById(opts.newArtifactId);
+    if (!newArtifact) {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: 'artifact_not_found',
+        nextAction: `Artifact ${opts.newArtifactId} does not exist. Create it first via pd candidate intake.`,
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      await stateManager.close();
+      return;
+    }
+    if (newArtifact.validationStatus !== 'validated') {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: `artifact_not_validated: ${newArtifact.validationStatus}`,
+        nextAction: `Artifact ${opts.newArtifactId} has validationStatus '${newArtifact.validationStatus}'. Run the production gate to validate it first.`,
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      await stateManager.close();
+      return;
+    }
+    const originalArtifact = await artifactStore.getArtifactById(existingApproval.artifactId);
+    if (!originalArtifact || !isArtifactRevisionOf(newArtifact, originalArtifact)) {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: 'artifact_lineage_mismatch',
+        nextAction: originalArtifact
+          ? `Artifact ${opts.newArtifactId} must reference ${originalArtifact.artifactId} or its source principle.`
+          : `Original artifact ${existingApproval.artifactId} is missing; restore it before editing this approval.`,
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      await stateManager.close();
+      return;
+    }
+
+    let editResult;
+    try {
+      editResult = await approvalStore.edit({
+        approvalId: opts.approvalId,
+        editedBy: 'operator',
+        newArtifactId: opts.newArtifactId,
+        editReason: opts.editReason,
+        now,
+      });
+    } catch (err: unknown) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: `edit_failed: ${errMsg}`,
+        nextAction: 'Check workspace DB integrity and that the approval + new artifact exist',
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit failed: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!editResult.ok) {
+      const result: EditApprovalResult = {
+        ok: false,
+        approvalId: opts.approvalId,
+        reason: editResult.error,
+        nextAction: editResult.error === 'not_found'
+          ? 'Check the approval ID on Console approvals page'
+          : `Approval is already decided (status: ${editResult.status ?? 'unknown'}). Only pending approvals can be edited.`,
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Edit refused: ${result.reason}`);
+        console.error(`Next action: ${result.nextAction}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const result: EditApprovalResult = {
+      ok: true,
+      approvalId: editResult.record.approvalId,
+      newArtifactId: editResult.record.artifactId,
+      previousArtifactId: editResult.record.previousArtifactId ?? undefined,
+      editedAt: editResult.record.editedAt ?? now,
+    };
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Approval edited: ${result.approvalId}`);
+      console.log(`  newArtifactId: ${result.newArtifactId}`);
+      if (result.previousArtifactId) {
+        console.log(`  previousArtifactId: ${result.previousArtifactId}`);
+      }
+      console.log(`  editedAt: ${result.editedAt}`);
+      console.log('Next action: review the new artifact, then approve via Console or `pd runtime activation dispatch`');
+    }
+  } catch (err: unknown) {
+    // P2 #5: initialize/DB exceptions must not break --json contract.
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const result: EditApprovalResult = {
+      ok: false,
+      approvalId: opts.approvalId,
+      reason: `initialize_failed: ${errMsg}`,
+      nextAction: 'Check workspace directory and DB integrity. Try `pd runtime diagnostics`.',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.reason}`);
+      console.error(`Next action: ${result.nextAction}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    await stateManager.close();
+  }
+}

package/src/index.ts

@@ -47,6 +47,7 @@ import { handleRuntimeDiagnosticsExport } from './commands/runtime-diagnostics-e
 import { handleRuntimeRecoverySweep } from './commands/runtime-recovery.js';
 import { handleRuntimeRecoveryFailedTasks } from './commands/runtime-recovery-failed-tasks.js';
 import { handleRuntimeActivationDispatch } from './commands/runtime-activation.js';
+import { handleRuntimeActivationDeactivate, handleRuntimeActivationList, handleRuntimeActivationEdit } from './commands/runtime-activation.js';
 import { handleProvenChannelBaseline } from './commands/proven-channel-baseline.js';
 import { handleDemoStoryA } from './commands/demo-story-a.js';
 import { handleRuntimeFeaturesStatus } from './commands/runtime-features.js';
@@ -577,7 +578,7 @@ const activationCmd = runtimeCmd
 activationCmd
   .command('dispatch')
   .description('Dispatch an activation for a rollout-reviewed artifact')
-  .requiredOption('-a, --artifact-id <id>', 'PIArtifact ID to activate')
+  .option('-a, --artifact-id <id>', 'PIArtifact ID to activate')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('-c, --channel <channel>', 'Activation channel (prompt|defer_archive)', 'prompt')
   .option('--dry-run', 'Dry-run mode (default, no writes)')
@@ -594,6 +595,61 @@ activationCmd
     });
   });
 
+// PRI-408 Contract E: Owner-initiated rollback/deactivate of an activation.
+// Idempotent — calling twice on the same ID is safe and returns ok=false with reason.
+activationCmd
+  .command('deactivate')
+  .description('Deactivate (rollback) an active activation — idempotent (PRI-408 Contract E)')
+  .option('-a, --activation-id <id>', 'Activation ID to deactivate')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handleRuntimeActivationDeactivate({
+      workspace: opts.workspace,
+      activationId: opts.activationId,
+      json: opts.json,
+    });
+  });
+
+// PRI-408 Contract D: Owner observability — list current activations.
+activationCmd
+  .command('list')
+  .description('List activations (default: active only) — PRI-408 Contract D observability')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('-c, --channel <channel>', 'Filter by channel (prompt|code_tool_hook)')
+  .option('--include-deactivated', 'Include deactivated records in output')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handleRuntimeActivationList({
+      workspace: opts.workspace,
+      channel: opts.channel,
+      includeDeactivated: opts.includeDeactivated,
+      json: opts.json,
+    });
+  });
+
+// P1 #2 fix: Owner edit entry point — swap a pending approval's artifact.
+// Required because ApprovalQueue.edit() was dead code with no CLI/OpenClaw entry.
+// P2 #5: use .option() instead of .requiredOption() so missing-flag errors
+// produce structured JSON output via the handler, not Commander's pre-handler exit.
+activationCmd
+  .command('edit')
+  .description('Edit a pending approval to swap its artifact — P1 #2 owner edit entry point')
+  .option('-a, --approval-id <id>', 'Approval ID to edit (must be pending)')
+  .option('-n, --new-artifact-id <id>', 'New PIArtifact ID to swap to')
+  .option('-r, --edit-reason <text>', 'Reason for the edit')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handleRuntimeActivationEdit({
+      workspace: opts.workspace,
+      approvalId: opts.approvalId,
+      newArtifactId: opts.newArtifactId,
+      editReason: opts.editReason,
+      json: opts.json,
+    });
+  });
+
 const diagnosticsCmd = runtimeCmd
   .command('diagnostics')
   .description('Control plane diagnostic bundle operations');

package/src/services/rulehost-pipeline-runner.ts

@@ -42,6 +42,8 @@ import {
   runAdversarialLoop,
   evaluateInRefinerSandbox,
   DEFAULT_MAX_ROUNDS,
+  SqliteApprovalQueueStore,
+  getChannelRiskLevel,
 } from '@principles/core/runtime-v2';
 import type {
   AdversarialLoopResult,
@@ -49,6 +51,7 @@ import type {
   PeerRunnerResult,
   RefinerRuleHostGateDeps,
   PIArtifactStore,
+  ApprovalRecord,
 } from '@principles/core/runtime-v2';
 /* eslint-disable @typescript-eslint/no-use-before-define -- helpers declared after main, matching codebase convention */
 import { compileDemoRule } from './demo-rule-compiler.js';
@@ -168,6 +171,14 @@ export interface RuleHostPipelineResult {
   readonly ruleArtifactId: string | null;
   /** Principle artifact ID (always present when scribe ran). */
   readonly principleArtifactId: string | null;
+  /**
+   * Approval ID when the candidate was auto-enqueued into the ApprovalQueue.
+   * Present when decision='candidate_ready_for_owner_review' and the pipeline
+   * successfully enqueued the candidate for owner review (P1 #1 fix).
+   * Null when the candidate was not enqueued (text_principle_only, rejected,
+   * or enqueue failed — check degradationReason for details).
+   */
+  readonly approvalId: string | null;
   /** Structured reason when decision is not candidate_ready_for_owner_review. */
   readonly degradationReason?: string;
 }
@@ -366,6 +377,44 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
       ? 'candidate_ready_for_owner_review' as const
       : 'generation_rejected' as const;
 
+    // P1 #1 fix: auto-enqueue the candidate into the ApprovalQueue so the
+    // owner can review it. Without this, the pipeline produces a candidate
+    // artifact but it never enters the approval queue — the production chain
+    // is broken at step 2→3. Tests manually called enqueue(); production did not.
+    let approvalId: string | null = null;
+    if (pipelineDecision === 'candidate_ready_for_owner_review' && loopResult.ruleArtifactId) {
+      try {
+        const approvalStore = new SqliteApprovalQueueStore(stateManager.connection);
+        const riskLevel = getChannelRiskLevel(channel);
+        const enqueuedRecord: ApprovalRecord = await approvalStore.enqueue({
+          artifactId: loopResult.ruleArtifactId,
+          channel,
+          riskLevel,
+          summary: `RuleHost pipeline candidate for pain ${opts.painId}`,
+          triggerReason: `adversarial_loop_approved: pain=${opts.painId}, rule=${loopResult.ruleArtifactId}`,
+        }, new Date().toISOString());
+        const { approvalId: enqueuedApprovalId } = enqueuedRecord;
+        approvalId = enqueuedApprovalId;
+        onProgress('adversarial_loop', 'succeeded', `auto-enqueued as approval ${approvalId}`);
+      } catch (err: unknown) {
+        // Enqueue failed — the candidate artifact exists but is not in the
+        // approval queue. Degrade gracefully with a structured reason (ERR-002).
+        const enqueueErr = err instanceof Error ? err.message : String(err);
+        const degradeReason = `candidate_approved_but_enqueue_failed: ${enqueueErr}. Manual enqueue required: pd runtime activation dispatch --artifact-id ${loopResult.ruleArtifactId} --channel ${channel}`;
+        return {
+          decision: pipelineDecision,
+          painId: opts.painId,
+          stages,
+          scribeTaskId,
+          adversarialLoop: loopResult,
+          ruleArtifactId: loopResult.ruleArtifactId,
+          principleArtifactId: loopResult.principleArtifactId,
+          approvalId: null,
+          degradationReason: degradeReason,
+        };
+      }
+    }
+
     return {
       decision: pipelineDecision,
       painId: opts.painId,
@@ -374,6 +423,7 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
       adversarialLoop: loopResult,
       ruleArtifactId: loopResult.ruleArtifactId,
       principleArtifactId: loopResult.principleArtifactId,
+      approvalId,
       degradationReason: loopResult.degradationReason,
     };
   } finally {
@@ -533,6 +583,7 @@ function rejectedResult(painId: string, stages: RuleHostPipelineStage[], degrada
     scribeTaskId: null,
     ruleArtifactId: null,
     principleArtifactId: null,
+    approvalId: null,
     degradationReason,
   };
 }
@@ -567,6 +618,7 @@ async function textPrincipleOnlyResult(
       scribeTaskId,
       ruleArtifactId: null,
       principleArtifactId: principleArt?.artifactId ?? null,
+      approvalId: null,
       degradationReason: `code_rule_capability_off: ${disabledReason}`,
     };
   } catch (error: unknown) {
@@ -578,6 +630,7 @@ async function textPrincipleOnlyResult(
       scribeTaskId,
       ruleArtifactId: null,
       principleArtifactId: null,
+      approvalId: null,
       degradationReason: `code_rule_capability_off: ${disabledReason}; principle_artifact_lookup_failed: ${message}`,
     };
   }

package/tests/commands/cli-command-tree.test.ts

@@ -62,4 +62,18 @@ describe('CLI command tree structure', () => {
     const output = runPdHelp(['runtime', '--help']);
     expect(output).toMatch(/health\s/);
   });
+
+  it('activation edit command exists under runtime activation (pd runtime activation edit --help)', () => {
+    const output = runPdHelp(['runtime', 'activation', 'edit', '--help']);
+    expect(output).toContain('--approval-id');
+    expect(output).toContain('--new-artifact-id');
+    expect(output).toContain('--edit-reason');
+    expect(output).toContain('--workspace');
+    expect(output).toContain('--json');
+  });
+
+  it('activation subcommand list includes edit (pd runtime activation --help)', () => {
+    const output = runPdHelp(['runtime', 'activation', '--help']);
+    expect(output).toMatch(/edit\s/);
+  });
 });