@vypdev/copilot 3.10.5 → 3.10.6

package/deployment-recovery/action.yml

@@ -0,0 +1,52 @@
+name: Inspect unpublished candidate replacement
+description: Read-only native prerequisite and replay inspection before project preparation.
+inputs:
+  token:
+    description: Existing product token; this action performs only native reads.
+    required: true
+  issue:
+    description: Positive launcher issue.
+    required: true
+  operation-id:
+    description: Exact previous deployment operation.
+    required: true
+  expected-revision:
+    description: Exact previous durable revision.
+    required: true
+  version:
+    description: Exact unpublished version.
+    required: true
+  source-sha:
+    description: Reviewed corrected source before complete preparation.
+    required: true
+  confirm-unpublished:
+    description: Explicit maintainer confirmation after inspecting every project registry.
+    default: 'false'
+  issue-workflow-profile:
+    description: Same enabled workflows and field mappings as the ordinary preparation action.
+    default: ''
+  release-label:
+    description: Configured release-kind label.
+    default: release
+  hotfix-label:
+    description: Configured hotfix-kind label.
+    default: hotfix
+  repository-locale:
+    description: Repository Summary language; English and Spanish have static catalogs.
+    default: en-US
+outputs:
+  mode:
+    description: prepare requires full validation; recover reuses the recorded candidate; recorded does not mutate.
+  source-branch:
+    description: Native operation-owned source branch.
+  candidate-sha:
+    description: Reviewed source for new preparation, or existing validated successor for recovery.
+  production-base-sha:
+    description: Native base for fresh replacement or the recorded replacement base for recovery.
+  operation-id:
+    description: Exact previous operation.
+  expected-revision:
+    description: Exact previous revision.
+runs:
+  using: node24
+  main: index.cjs

package/deployment-recovery/index.cjs

@@ -0,0 +1,3 @@
+'use strict';
+
+void require('../build/deployment_recovery/index.js').runDeploymentCandidatePreflightAction();

package/issue-admission/action.yml

@@ -0,0 +1,41 @@
+name: Copilot issue event admission
+description: Read-only issue admission and successful-reconciliation receipts, without agent setup.
+inputs:
+  issue-event-admission-mode:
+    description: Isolated mode, inspect before work or record after successful work.
+    required: true
+  token:
+    description: Existing product credential for native identity and issue reads.
+    required: true
+  configuration:
+    description: Repository Variables snapshot used only in a credential-free state digest.
+    default: ''
+  repository-locale:
+    description: Job Summary locale, English or Spanish with regional and English fallback.
+    default: en-US
+  deploy-label:
+    description: Deployment intent label; it must never be coalesced.
+    default: deploy
+  release-label:
+    description: Release intent label; must match the normal Action.
+    default: release
+  hotfix-label:
+    description: Hotfix intent label; must match the normal Action.
+    default: hotfix
+  receipt-key:
+    description: Exact digest returned by this run's successful inspect step.
+    default: ''
+outputs:
+  execute:
+    description: True only when the normal guarded issue pipeline should run.
+  reason:
+    description: Closed admission reason; no issue text or credentials.
+  receipt-key:
+    description: Opaque native state, workflow and runtime digest.
+  receipt-name:
+    description: Artifact name after an unchanged successful reconciliation.
+  receipt-path:
+    description: Private temporary receipt file for native artifact upload.
+runs:
+  using: node24
+  main: index.cjs

package/issue-admission/index.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+// Metadata's required:true is advisory; never fall through to the mutation entry.
+const mode = (process.env['INPUT_ISSUE-EVENT-ADMISSION-MODE'] ?? '').trim();
+if (mode !== 'inspect' && mode !== 'record') {
+  process.stderr.write('Issue admission requires inspect or record mode. No pipeline was started.\n');
+  process.exitCode = 1;
+} else {
+  // This isolated action has no JSON input-override channel or native worker mode.
+  delete process.env.INPUT_VARS_JSON;
+  process.env.COPILOT_ISSUE_ADMISSION_BOOTSTRAP = '1';
+  void require('../build/github_action/index.js').runGitHubActionEntry();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vypdev/copilot",
-  "version": "3.10.5",
+  "version": "3.10.6",
   "packageManager": "pnpm@10.12.4",
   "pnpm": {
     "overrides": {
@@ -34,9 +34,12 @@
   },
   "files": [
     "action.yml",
+    "issue-admission/",
+    "deployment-recovery/",
     "build/cli/index.js",
     "build/web/",
     "build/github_action/index.js",
+    "build/deployment_recovery/index.js",
     "build/api/index.js",
     "build/api/src/",
     "setup/ISSUE_TEMPLATE/",
@@ -55,7 +58,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "node scripts/clean-generated-bundles.cjs && pnpm run build:web && ncc build src/actions/github_action.ts -o build/github_action && ncc build src/cli.ts -o build/cli && ncc build src/api.ts -o build/api && node scripts/prepare-generated-bundles.cjs && node scripts/set-cli-executable.cjs",
+    "build": "node scripts/clean-generated-bundles.cjs && pnpm run build:web && ncc build src/actions/github_action.ts -o build/github_action && ncc build src/actions/deployment_candidate_preflight_action.ts -o build/deployment_recovery && ncc build src/cli.ts -o build/cli && ncc build src/api.ts -o build/api && node scripts/prepare-generated-bundles.cjs && node scripts/set-cli-executable.cjs && pnpm run build:extension",
     "build:web": "vite build --config web/vite.config.mts",
     "check:web": "svelte-check --tsconfig web/tsconfig.json && vite build --config web/vite.config.mts",
     "validate:build": "node scripts/validate-build.cjs",
@@ -63,20 +66,27 @@
     "smoke:npm-package": "node scripts/smoke-test-npm-package.cjs",
     "test": "jest",
     "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage --json --outputFile=coverage/setup-acceptance-jest.json && node scripts/validate-coverage-budgets.cjs && node scripts/validate-setup-assistant-acceptance.cjs coverage/setup-acceptance-jest.json",
+    "test:coverage": "jest --coverage --json --outputFile=coverage/setup-acceptance-jest.json && node scripts/validate-coverage-budgets.cjs && node scripts/validate-setup-assistant-acceptance.cjs coverage/setup-acceptance-jest.json && pnpm run test:extension",
     "eval:bugbot": "jest src/tooling/__tests__/bugbot_quality_eval.test.ts src/tooling/__tests__/bugbot_benchmark.test.ts --runInBand",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && pnpm run typecheck:extension",
     "metrics:architecture": "node scripts/collect-architecture-metrics.cjs",
-    "lint": "eslint src",
+    "lint": "eslint src extension",
     "validate:agent-docs": "node scripts/validate-agent-documentation.cjs",
     "validate:docs-page": "node scripts/validate-docs-page-assets.cjs",
     "validate:documentation": "node scripts/validate-documentation-contract.cjs",
     "validate:workflows": "node scripts/validate-workflow-contract.cjs",
-    "generate:specifications": "node scripts/validate-specification-catalog.cjs --write && node scripts/validate-github-communication-test-budget.cjs",
-    "validate:specifications": "node scripts/validate-specification-catalog.cjs && node scripts/validate-github-communication-test-budget.cjs",
+    "generate:specifications": "node scripts/validate-specification-catalog.cjs --write && node scripts/validate-github-communication-test-budget.cjs && pnpm run validate:browser-extension-specifications",
+    "validate:specifications": "node scripts/validate-specification-catalog.cjs && node scripts/validate-github-communication-test-budget.cjs && pnpm run validate:browser-extension-specifications",
     "validate:setup-acceptance": "node scripts/validate-setup-assistant-acceptance.cjs",
     "lint:fix": "eslint src --fix",
-    "postinstall": "node scripts/install-git-hooks.cjs"
+    "postinstall": "node scripts/install-git-hooks.cjs",
+    "validate:browser-extension-specifications": "node --test test-support/browser-extension-specifications.test.cjs && node scripts/validate-browser-extension-specifications.cjs",
+    "build:extension": "pnpm --dir extension run build",
+    "typecheck:extension": "pnpm --dir extension run typecheck",
+    "test:extension": "pnpm --dir extension run test",
+    "validate:extension": "pnpm --dir extension run validate",
+    "test:browsers:extension": "pnpm --dir extension run test:browsers",
+    "build:safari:extension": "pnpm --dir extension run build:safari"
   },
   "keywords": [],
   "author": "Efra Espada",
@@ -98,6 +108,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.9.1",
     "@vercel/ncc": "^0.36.1",
+    "ajv": "6.15.0",
     "eslint": "^10.10.0",
     "jest": "^30.5.1",
     "svelte": "^5.57.1",

package/setup/workflows/copilot_commit.yml

@@ -19,6 +19,7 @@ jobs:
       group: copilot-push-${{ github.repository }}-${{ github.ref_name }}
       cancel-in-progress: true
     permissions:
+      checks: write
       contents: read
     steps:
       - name: Checkout Repository
@@ -104,6 +105,7 @@ jobs:
           fixer-executable: ${{ vars.FIXER_EXECUTABLE }}
           token: ${{ secrets.PAT }}
         env:
+          COPILOT_EVIDENCE_TOKEN: ${{ github.token }}
           AGENT_PROVIDER: ${{ vars.AGENT_PROVIDER || 'codex' }}
           AGENT_MODEL_PROVIDER: ${{ vars.AGENT_MODEL_PROVIDER || 'openai' }}
           AGENT_MODEL: ${{ vars.AGENT_MODEL }}

package/setup/workflows/copilot_issue.yml

@@ -4,9 +4,40 @@ on:
   issues:
     types: [opened, reopened, closed, edited, labeled, unlabeled, assigned, unassigned]
 
+# Keep every pending lifecycle event; never replace a start/reopen with a label event.
+# GitHub bounds this queue at 100 pending runs. Independent issues use different groups.
+concurrency:
+  group: copilot-issue-${{ github.repository }}-${{ github.event.issue.number }}
+  cancel-in-progress: false
+  queue: max
+
 jobs:
+  issue-admission:
+    name: Admit issue event
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      execute: ${{ steps.inspect.outputs.execute }}
+      receipt-key: ${{ steps.inspect.outputs.receipt-key }}
+    steps:
+      - name: Inspect native issue event
+        id: inspect
+        uses: vypdev/copilot/issue-admission@v3
+        with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issue-event-admission-mode: inspect
+          token: ${{ secrets.PAT }}
+          configuration: ${{ format('[{0},{1},{2},{3},{4},{5},{6},{7},{8},{9},{10},{11},{12},{13},{14},{15},{16},{17},{18},{19},{20},{21},{22},{23},{24},{25},{26},{27},{28},{29},{30},{31},{32},{33},{34},{35},{36},{37},{38},{39},{40},{41},{42},{43},{44},{45},{46},{47},{48},{49},{50},{51},{52},{53},{54},{55},{56},{57},{58},{59},{60},{61},{62},{63},{64}]', toJSON(vars.AGENT_ALLOWED_MODELS), toJSON(vars.AGENT_ALLOWED_MODEL_PROVIDERS), toJSON(vars.AGENT_EFFORT), toJSON(vars.AGENT_EXECUTABLE), toJSON(vars.AGENT_MODEL), toJSON(vars.AGENT_MODEL_PROVIDER), toJSON(vars.AGENT_PROVIDER), toJSON(vars.AI_IGNORE_FILES), toJSON(vars.AI_INCLUDE_REASONING), toJSON(vars.AI_MEMBERS_ONLY), toJSON(vars.AI_PULL_REQUEST_DESCRIPTION_MODE), toJSON(vars.BUGBOT_AUTOFIX_VERIFY_COMMANDS), toJSON(vars.BUGBOT_COMMENT_LIMIT), toJSON(vars.BUGBOT_DRY_RUN), toJSON(vars.BUGBOT_EFFORT), toJSON(vars.BUGBOT_FAIL_ON_UNRESOLVED), toJSON(vars.BUGBOT_ORGANIZATION_RULES), toJSON(vars.BUGBOT_REVIEW_DRAFTS), toJSON(vars.BUGBOT_SEVERITY), toJSON(vars.BUGBOT_SUGGESTED_CHANGES), toJSON(vars.BUGBOT_TELEMETRY), toJSON(vars.BUGBOT_TRACE_RULES), toJSON(vars.BUGFIX_TREE), toJSON(vars.CHORE_TREE), toJSON(vars.COMMIT_PREFIX_TRANSFORMS), toJSON(vars.COPILOT_ISSUE_WORKFLOW_PROFILE), toJSON(vars.DEBUG), toJSON(vars.DEPLOY_LABEL), toJSON(vars.DESIRED_ASSIGNEES_COUNT), toJSON(vars.DESIRED_REVIEWERS_COUNT), toJSON(vars.DEVELOPMENT_BRANCH), toJSON(vars.DOCS_TREE), toJSON(vars.FEATURE_TREE), toJSON(vars.FINDINGS_EFFORT), toJSON(vars.FINDINGS_EXECUTABLE), toJSON(vars.FINDINGS_MODEL), toJSON(vars.FINDINGS_MODEL_PROVIDER), toJSON(vars.FINDINGS_PROVIDER), toJSON(vars.FIXER_EFFORT), toJSON(vars.FIXER_EXECUTABLE), toJSON(vars.FIXER_MODEL), toJSON(vars.FIXER_MODEL_PROVIDER), toJSON(vars.FIXER_PROVIDER), toJSON(vars.HOTFIX_TREE), toJSON(vars.ISSUES_LOCALE), toJSON(vars.ISSUE_MANAGED_BRANCHES), toJSON(vars.MAIN_BRANCH), toJSON(vars.PLANNER_EFFORT), toJSON(vars.PLANNER_EXECUTABLE), toJSON(vars.PLANNER_MODEL), toJSON(vars.PLANNER_MODEL_PROVIDER), toJSON(vars.PLANNER_PROVIDER), toJSON(vars.PRE_BRANCH_SDD), toJSON(vars.PROJECT_COLUMN_ISSUE_CREATED), toJSON(vars.PROJECT_COLUMN_ISSUE_IN_PROGRESS), toJSON(vars.PROJECT_COLUMN_PULL_REQUEST_CREATED), toJSON(vars.PROJECT_COLUMN_PULL_REQUEST_IN_PROGRESS), toJSON(vars.PROJECT_IDS), toJSON(vars.PULL_REQUESTS_LOCALE), toJSON(vars.RELEASE_TREE), toJSON(vars.REOPEN_ISSUE_ON_PUSH), toJSON(vars.REPOSITORY_LOCALE), toJSON(vars.REVIEWER_PROVIDER), toJSON(vars.TESTER_PROVIDER), toJSON(vars.VERIFICATION_SETUP)) }}
+          deploy-label: ${{ vars.DEPLOY_LABEL || 'deploy' }}
+        env:
+          COPILOT_ISSUE_ADMISSION_TOKEN: ${{ github.token }}
+
   copilot-issues:
-    if: ${{ (github.event.action == 'closed' && github.event.issue.state == 'closed') || vars.COPILOT_BOT_LOGIN == '' || github.actor != vars.COPILOT_BOT_LOGIN }}
+    needs: issue-admission
+    if: ${{ needs.issue-admission.outputs.execute == 'true' }}
     name: Copilot - Issue
     runs-on: ubuntu-latest
     timeout-minutes: 120
@@ -24,7 +55,9 @@ jobs:
       # Optional trusted-main setup: VERIFICATION_SETUP=true and .github/actions/copilot-verification-setup/action.yml.
       # https://docs.page/vypdev/copilot/security-operations/operations/verification#repository-verification-prerequisites
       - uses: vypdev/copilot@v3
+        id: copilot
         with:
+          deploy-label: ${{ vars.DEPLOY_LABEL || 'deploy' }}
           repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
           issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
           pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
@@ -101,3 +134,26 @@ jobs:
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           CURSOR_API_KEY: ${{ (vars.AGENT_PROVIDER == 'cursor' || vars.FINDINGS_PROVIDER == 'cursor' || vars.FIXER_PROVIDER == 'cursor' || vars.PLANNER_PROVIDER == 'cursor' || vars.REVIEWER_PROVIDER == 'cursor' || vars.TESTER_PROVIDER == 'cursor') && secrets.CURSOR_API_KEY || '' }}
           CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
+
+      - name: Record unchanged successful reconciliation
+        id: receipt
+        if: ${{ success() && steps.copilot.outcome == 'success' && needs.issue-admission.outputs.receipt-key != '' }}
+        continue-on-error: true
+        uses: vypdev/copilot/issue-admission@v3
+        with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issue-event-admission-mode: record
+          token: ${{ secrets.PAT }}
+          configuration: ${{ format('[{0},{1},{2},{3},{4},{5},{6},{7},{8},{9},{10},{11},{12},{13},{14},{15},{16},{17},{18},{19},{20},{21},{22},{23},{24},{25},{26},{27},{28},{29},{30},{31},{32},{33},{34},{35},{36},{37},{38},{39},{40},{41},{42},{43},{44},{45},{46},{47},{48},{49},{50},{51},{52},{53},{54},{55},{56},{57},{58},{59},{60},{61},{62},{63},{64}]', toJSON(vars.AGENT_ALLOWED_MODELS), toJSON(vars.AGENT_ALLOWED_MODEL_PROVIDERS), toJSON(vars.AGENT_EFFORT), toJSON(vars.AGENT_EXECUTABLE), toJSON(vars.AGENT_MODEL), toJSON(vars.AGENT_MODEL_PROVIDER), toJSON(vars.AGENT_PROVIDER), toJSON(vars.AI_IGNORE_FILES), toJSON(vars.AI_INCLUDE_REASONING), toJSON(vars.AI_MEMBERS_ONLY), toJSON(vars.AI_PULL_REQUEST_DESCRIPTION_MODE), toJSON(vars.BUGBOT_AUTOFIX_VERIFY_COMMANDS), toJSON(vars.BUGBOT_COMMENT_LIMIT), toJSON(vars.BUGBOT_DRY_RUN), toJSON(vars.BUGBOT_EFFORT), toJSON(vars.BUGBOT_FAIL_ON_UNRESOLVED), toJSON(vars.BUGBOT_ORGANIZATION_RULES), toJSON(vars.BUGBOT_REVIEW_DRAFTS), toJSON(vars.BUGBOT_SEVERITY), toJSON(vars.BUGBOT_SUGGESTED_CHANGES), toJSON(vars.BUGBOT_TELEMETRY), toJSON(vars.BUGBOT_TRACE_RULES), toJSON(vars.BUGFIX_TREE), toJSON(vars.CHORE_TREE), toJSON(vars.COMMIT_PREFIX_TRANSFORMS), toJSON(vars.COPILOT_ISSUE_WORKFLOW_PROFILE), toJSON(vars.DEBUG), toJSON(vars.DEPLOY_LABEL), toJSON(vars.DESIRED_ASSIGNEES_COUNT), toJSON(vars.DESIRED_REVIEWERS_COUNT), toJSON(vars.DEVELOPMENT_BRANCH), toJSON(vars.DOCS_TREE), toJSON(vars.FEATURE_TREE), toJSON(vars.FINDINGS_EFFORT), toJSON(vars.FINDINGS_EXECUTABLE), toJSON(vars.FINDINGS_MODEL), toJSON(vars.FINDINGS_MODEL_PROVIDER), toJSON(vars.FINDINGS_PROVIDER), toJSON(vars.FIXER_EFFORT), toJSON(vars.FIXER_EXECUTABLE), toJSON(vars.FIXER_MODEL), toJSON(vars.FIXER_MODEL_PROVIDER), toJSON(vars.FIXER_PROVIDER), toJSON(vars.HOTFIX_TREE), toJSON(vars.ISSUES_LOCALE), toJSON(vars.ISSUE_MANAGED_BRANCHES), toJSON(vars.MAIN_BRANCH), toJSON(vars.PLANNER_EFFORT), toJSON(vars.PLANNER_EXECUTABLE), toJSON(vars.PLANNER_MODEL), toJSON(vars.PLANNER_MODEL_PROVIDER), toJSON(vars.PLANNER_PROVIDER), toJSON(vars.PRE_BRANCH_SDD), toJSON(vars.PROJECT_COLUMN_ISSUE_CREATED), toJSON(vars.PROJECT_COLUMN_ISSUE_IN_PROGRESS), toJSON(vars.PROJECT_COLUMN_PULL_REQUEST_CREATED), toJSON(vars.PROJECT_COLUMN_PULL_REQUEST_IN_PROGRESS), toJSON(vars.PROJECT_IDS), toJSON(vars.PULL_REQUESTS_LOCALE), toJSON(vars.RELEASE_TREE), toJSON(vars.REOPEN_ISSUE_ON_PUSH), toJSON(vars.REPOSITORY_LOCALE), toJSON(vars.REVIEWER_PROVIDER), toJSON(vars.TESTER_PROVIDER), toJSON(vars.VERIFICATION_SETUP)) }}
+          deploy-label: ${{ vars.DEPLOY_LABEL || 'deploy' }}
+          receipt-key: ${{ needs.issue-admission.outputs.receipt-key }}
+
+      - name: Retain successful reconciliation receipt
+        if: ${{ steps.receipt.outputs.receipt-path != '' }}
+        continue-on-error: true
+        uses: actions/upload-artifact@v5
+        with:
+          name: ${{ steps.receipt.outputs.receipt-name }}
+          path: ${{ steps.receipt.outputs.receipt-path }}
+          retention-days: 1
+          if-no-files-found: error

package/setup/workflows/hotfix_workflow.yml

@@ -8,11 +8,25 @@ on:
         required: true
         default: prepare
         type: choice
+        # Add replace only after configuring the complete project verifier and enabling it below.
         options: [prepare, publish, resume]
       operation-id:
         description: 'Internal durable operation identifier'
         required: false
         default: ''
+      expected-revision:
+        description: 'Current durable revision; required only for replace'
+        required: false
+        default: ''
+      source-sha:
+        description: 'Reviewed corrected source before complete replacement preparation'
+        required: false
+        default: ''
+      confirm-unpublished:
+        description: 'Confirm the exact version is unpublished in every project registry'
+        type: boolean
+        required: false
+        default: false
       version:
         description: 'Hotfix version (MAJOR.MINOR.PATCH)'
         required: false
@@ -50,6 +64,11 @@ jobs:
           ISSUE: ${{ inputs.issue }}
           TITLE: ${{ inputs.title }}
           CHANGELOG: ${{ inputs.changelog }}
+          EXPECTED_REVISION: ${{ inputs.expected-revision }}
+          SOURCE_SHA: ${{ inputs.source-sha }}
+          CONFIRM_UNPUBLISHED: ${{ inputs.confirm-unpublished }}
+          # Workflow-owned opt-in; never supplied by an issue or dispatch input.
+          REPLACEMENT_ENABLED: 'false'
         with:
           script: |
             const mode = process.env.MODE;
@@ -59,6 +78,10 @@ jobs:
             const issue = Number(issueText);
             const title = process.env.TITLE || '';
             const changelog = process.env.CHANGELOG || '';
+            const revisionText = process.env.EXPECTED_REVISION || '';
+            const revision = Number(revisionText);
+            const sourceSha = process.env.SOURCE_SHA || '';
+            const confirmed = process.env.CONFIRM_UNPUBLISHED || 'false';
             const errors = [];
             if (!/^[1-9][0-9]*$/.test(issueText) || !Number.isSafeInteger(issue) || issue < 1) errors.push('Issue must be a positive safe integer.');
             if (!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(version)) errors.push('Version must use MAJOR.MINOR.PATCH.');
@@ -66,25 +89,89 @@ jobs:
               if (operationId) errors.push('Operation ID must be empty in prepare mode.');
               if (!title || title.length > 1000) errors.push('Title must contain 1-1000 characters.');
               if (!changelog || changelog.length > 50000) errors.push('Changelog must contain 1-50000 characters.');
+            } else if (mode === 'replace') {
+              if (process.env.REPLACEMENT_ENABLED !== 'true') errors.push('Candidate replacement is disabled. Configure the complete project verifier, enable it in this workflow and then add replace to the choices.');
+              if (!/^[A-Za-z0-9][A-Za-z0-9._-]{7,127}$/.test(operationId)) errors.push('Operation ID is invalid.');
+              if (!/^[1-9][0-9]*$/.test(revisionText) || !Number.isSafeInteger(revision) || revision < 1 || revision >= Number.MAX_SAFE_INTEGER) errors.push('Replacement revision is invalid.');
+              if (!/^[a-f0-9]{40}$/.test(sourceSha)) errors.push('Replacement source must be a full reviewed SHA.');
+              if (version.length > 64 || confirmed !== 'true') errors.push('Confirm the exact unpublished replacement version.');
+              if (title || changelog) errors.push('Replacement preserves the stored title and changelog.');
             } else if (mode === 'publish' || mode === 'resume') {
               if (!/^[A-Za-z0-9][A-Za-z0-9._-]{7,127}$/.test(operationId)) errors.push('Operation ID is invalid.');
               if (title || changelog) errors.push('Title and changelog must be empty in publish or resume mode.');
-            } else errors.push('Mode must be prepare, publish, or resume.');
+            } else errors.push('Mode must be prepare, replace, publish, or resume.');
+            if (mode !== 'replace' && (revisionText || sourceSha || confirmed !== 'false')) errors.push('Replacement proof inputs are allowed only in replace mode.');
             if (errors.length) core.setFailed(errors.join(' '));
 
+  candidate-preflight:
+    name: Inspect unpublished candidate replacement
+    if: ${{ inputs.mode == 'replace' }}
+    runs-on: ubuntu-latest
+    needs: validate
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+      actions: read
+    outputs:
+      mode: ${{ steps.inspect.outputs.mode }}
+      source-branch: ${{ steps.inspect.outputs.source-branch }}
+      candidate-sha: ${{ steps.inspect.outputs.candidate-sha }}
+      production-base-sha: ${{ steps.inspect.outputs.production-base-sha }}
+      operation-id: ${{ steps.inspect.outputs.operation-id }}
+      expected-revision: ${{ steps.inspect.outputs.expected-revision }}
+    steps:
+      - name: Read native candidate authority
+        id: inspect
+        uses: vypdev/copilot/deployment-recovery@v3
+        with:
+          issue: ${{ inputs.issue }}
+          operation-id: ${{ inputs.operation-id }}
+          expected-revision: ${{ inputs.expected-revision }}
+          version: ${{ inputs.version }}
+          source-sha: ${{ inputs.source-sha }}
+          confirm-unpublished: ${{ inputs.confirm-unpublished }}
+          issue-workflow-profile: ${{ vars.COPILOT_ISSUE_WORKFLOW_PROFILE || '' }}
+          release-label: release
+          hotfix-label: hotfix
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          token: ${{ secrets.PAT }}
+
   prepare-version-files:
     name: Prepare and validate hotfix
-    if: ${{ inputs.mode == 'prepare' }}
+    if: ${{ !cancelled() && needs.validate.result == 'success' && (inputs.mode == 'prepare' || (inputs.mode == 'replace' && needs.candidate-preflight.result == 'success' && needs.candidate-preflight.outputs.mode == 'prepare')) }}
     runs-on: ubuntu-latest
-    needs: validate
+    needs: [validate, candidate-preflight]
     timeout-minutes: 30
     permissions:
       contents: write
+    outputs:
+      candidate-sha: ${{ steps.candidate-identity.outputs.candidate-sha }}
     steps:
       - uses: actions/checkout@v5
         with:
           persist-credentials: true
+          ref: ${{ needs.candidate-preflight.outputs.source-branch || github.ref }}
+      - name: Verify reviewed replacement source
+        if: ${{ inputs.mode == 'replace' }}
+        uses: actions/github-script@v9
+        env:
+          EXPECTED_SHA: ${{ inputs.source-sha }}
+        with:
+          script: |
+            const { execFileSync } = require('node:child_process');
+            const current = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+            if (!/^[a-f0-9]{40}$/.test(process.env.EXPECTED_SHA || '') || current !== process.env.EXPECTED_SHA) {
+              core.setFailed('The reviewed replacement source moved before preparation. No new candidate proof is available.');
+            }
       # Add project-specific version, build, validation, smoke-test and generated-file steps here.
+      - name: Complete fresh replacement verification
+        id: replacement-verification
+        if: ${{ inputs.mode == 'replace' }}
+        run: |
+          echo "Configure this step with every required project validator, including registry vacancy, before enabling candidate replacement."
+          exit 1
       - name: Commit prepared hotfix files
         uses: EndBug/add-and-commit@v9
         with:
@@ -93,12 +180,29 @@ jobs:
           committer_email: actions@github.com
           default_author: user_info
           message: 'gh-action: prepare hotfix ${{ inputs.version }}'
+      - name: Confirm prepared replacement identity
+        id: candidate-identity
+        if: ${{ inputs.mode == 'replace' }}
+        uses: actions/github-script@v9
+        env:
+          SOURCE_BRANCH: ${{ needs.candidate-preflight.outputs.source-branch }}
+          VERIFICATION_RESULT: ${{ steps.replacement-verification.outcome }}
+        with:
+          script: |
+            if (process.env.VERIFICATION_RESULT !== 'success') throw new Error('Complete replacement verification was not confirmed.');
+            const { execFileSync } = require('node:child_process');
+            const candidate = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+            const dirty = execFileSync('git', ['status', '--porcelain'], { encoding: 'utf8' }).trim();
+            if (!/^[a-f0-9]{40}$/.test(candidate) || !process.env.SOURCE_BRANCH || dirty) throw new Error('The prepared candidate is not an exact clean commit.');
+            const response = await github.rest.git.getRef({ ...context.repo, ref: `heads/${process.env.SOURCE_BRANCH}` });
+            if (response.data.object?.type !== 'commit' || response.data.object.sha !== candidate) throw new Error('The prepared source moved before candidate proof was recorded.');
+            core.setOutput('candidate-sha', candidate);
 
   promote:
     name: Open production promotion
-    if: ${{ inputs.mode == 'prepare' }}
+    if: ${{ !cancelled() && needs.validate.result == 'success' && ((inputs.mode == 'prepare' && needs.prepare-version-files.result == 'success') || (inputs.mode == 'replace' && needs.candidate-preflight.result == 'success' && ((needs.candidate-preflight.outputs.mode == 'prepare' && needs.prepare-version-files.result == 'success' && needs.prepare-version-files.outputs.candidate-sha != '') || needs.candidate-preflight.outputs.mode == 'recover'))) }}
     runs-on: ubuntu-latest
-    needs: prepare-version-files
+    needs: [validate, candidate-preflight, prepare-version-files]
     timeout-minutes: 10
     permissions:
       contents: read
@@ -109,7 +213,9 @@ jobs:
       - uses: actions/checkout@v5
         with:
           persist-credentials: false
+          ref: ${{ inputs.mode == 'replace' && (needs.candidate-preflight.outputs.mode == 'recover' && needs.candidate-preflight.outputs.candidate-sha || needs.prepare-version-files.outputs.candidate-sha) || github.ref }}
       - name: Create or resume promotion PR
+        if: ${{ inputs.mode == 'prepare' }}
         uses: vypdev/copilot@v3
         with:
           single-action: prepare_deployment_action
@@ -140,6 +246,44 @@ jobs:
           issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
           pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           token: ${{ secrets.PAT }}
+      - name: Replace or recover unpublished candidate
+        if: ${{ inputs.mode == 'replace' }}
+        uses: vypdev/copilot@v3
+        with:
+          single-action: replace_deployment_action
+          single-action-operation-id: ${{ needs.candidate-preflight.outputs.operation-id }}
+          single-action-expected-revision: ${{ needs.candidate-preflight.outputs.expected-revision }}
+          single-action-reviewed-source-sha: ${{ inputs.source-sha }}
+          single-action-candidate-sha: ${{ needs.candidate-preflight.outputs.mode == 'recover' && needs.candidate-preflight.outputs.candidate-sha || needs.prepare-version-files.outputs.candidate-sha }}
+          single-action-production-base-sha: ${{ needs.candidate-preflight.outputs.production-base-sha }}
+          single-action-confirm-unpublished: ${{ inputs.confirm-unpublished }}
+          single-action-issue: ${{ inputs.issue }}
+          issue-workflow-profile: ${{ vars.COPILOT_ISSUE_WORKFLOW_PROFILE || '' }}
+          single-action-version: ${{ inputs.version }}
+          single-action-title: ${{ inputs.title }}
+          single-action-changelog: ${{ inputs.changelog }}
+          main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
+          development-branch: ${{ vars.DEVELOPMENT_BRANCH || 'develop' }}
+          release-tree: ${{ vars.RELEASE_TREE || 'release' }}
+          hotfix-tree: ${{ vars.HOTFIX_TREE || 'hotfix' }}
+          release-workflow: ${{ vars.RELEASE_WORKFLOW || 'release_workflow.yml' }}
+          hotfix-workflow: ${{ vars.HOTFIX_WORKFLOW || 'hotfix_workflow.yml' }}
+          release-reconciliation-strategy: ${{ vars.RELEASE_RECONCILIATION_STRATEGY || 'production-lineage' }}
+          hotfix-reconciliation-strategy: ${{ vars.HOTFIX_RECONCILIATION_STRATEGY || 'production-lineage' }}
+          reconciliation-pr-mode: ${{ vars.RECONCILIATION_PR_MODE || 'auto' }}
+          merge-queue-check-attestations: ${{ vars.MERGE_QUEUE_CHECK_ATTESTATIONS || '[]' }}
+          reconciliation-backmerge-mode: ${{ vars.RECONCILIATION_BACKMERGE_MODE || 'auto' }}
+          hotfix-active-release-policy: ${{ vars.HOTFIX_ACTIVE_RELEASE_POLICY || 'prefer-release' }}
+          reconciliation-tree: ${{ vars.RECONCILIATION_TREE || 'sync' }}
+          reconciliation-cleanup: ${{ vars.RECONCILIATION_CLEANUP || 'all' }}
+          reconciliation-issue-completion: ${{ vars.RECONCILIATION_ISSUE_COMPLETION || 'close' }}
+          orchestration-presentation-mode: ${{ vars.ORCHESTRATION_PRESENTATION_MODE || 'guided' }}
+          orchestration-diagrams: ${{ vars.ORCHESTRATION_DIAGRAMS || 'true' }}
+          orchestration-comment-mode: ${{ vars.ORCHESTRATION_COMMENT_MODE || 'update' }}
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
+          token: ${{ secrets.PAT }}
 
   publish:
     name: Publish accepted production commit
@@ -239,8 +383,8 @@ jobs:
     name: Report orchestration failure
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    needs: [validate, prepare-version-files, promote, publish, resume-reconciliation]
-    if: ${{ failure() && needs.validate.result == 'success' }}
+    needs: [validate, candidate-preflight, prepare-version-files, promote, publish, resume-reconciliation]
+    if: ${{ failure() && needs.validate.result == 'success' && inputs.mode != 'replace' }}
     permissions:
       issues: write
     steps: