@com55/node-red-ai-access 0.2.0-beta.6 → 0.2.0-beta.8

package/docs/api/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: Node-RED AI Access Plugin API
-  version: 0.1.1
+  version: 0.2.0-beta.8
   summary: Temporary, owner-approved Node-RED access for AI clients
   description: |
     REST surface exposed by the `@com55/node-red-ai-access` Node-RED plugin
@@ -10,8 +10,8 @@ info:
 
     **Git mental model:** a proposal is like a pull request. Human approve =
     merge; reject = close; withdraw = the author closes their own PR. If `rev` /
-    `expectedRev` does not match, treat it as a conflict: re-read the flow,
-    rebase the edit, and resubmit. Every access link can see all proposals
+    `expectedRev` does not match, open proposals auto-rebase; only overlapping
+    field changes block approval. Read `rebase.state` to assess readiness. Every access link can see all proposals
     (`mine: true|false`).
 
     ## Base path
@@ -173,7 +173,7 @@ info:
     (`invalid_filter` for list filters, `invalid_arguments` otherwise).
 
     On submit and on **get** of a **pending** proposal, responses may include
-    `conflictingProposals` (same-`expectedRev` peers or true node/field overlaps)
+    `conflictingProposals` (open proposals with overlapping node edits)
     with optional `overlappingNodeIds` / `overlappingFields`. List endpoints
     omit `conflictingProposals`. Submit, get, and list responses include
     `autoClosedCount` when that request auto-closed pending proposals as
@@ -184,17 +184,25 @@ info:
     `N validation errors` and every entry in `errors[]`. Duplicate node ids in a
     full tab or batch return `duplicate_node_id`.
 
-    Pending proposals whose `expectedRev` no longer matches the live flow rev
-    are auto-closed as `expired`. When a proposal is approved, other pending
-    proposals on the same flow become `superseded`. Closed proposals are never
-    conflicts.
+    Open proposals (`pending` or `conflict`) auto-rebase when live revisions change.
+    Disjoint node and tab fields merge automatically. Only fields changed on both
+    sides conflict (even identical edits); x/y never conflict and proposed positions
+    win ties. Env merges by unique name and entry field, credentials by key.
+    Duplicate env names fall back to atomic comparison with ambiguity warnings.
+    Conflicts block approval until resolved. Proposals expire only after the
+    configured `proposalTtlDays` (default 7). Approval rebases other open proposals;
+    legacy expired, rejected and superseded proposals stay closed.
 
     ## Withdraw
 
     The creating access link may withdraw its own pending proposal
     (`POST /proposals/{id}/withdraw`, GET `…/proposals/{id}/withdraw?confirm=1`,
     or MCP `withdraw_proposal`). GET withdraw requires `confirm=1` so prefetchers
-    cannot trigger it. Status becomes `withdrawn` (separate from admin
+    cannot trigger it. If the token is lost, a full (`*`) admin session may use
+    POST `/proposals/{id}/withdraw`. Other tokens remain blocked. Recovery is logged
+    as `proposal.withdrawn` with the admin identity, originalOwnerId, reason and
+    withdrawalAuthority=`admin-recovery` (owner-token withdrawals use `owner-token`).
+    Status becomes `withdrawn` (separate from admin
     `rejected`).
 
     ## Known issues
@@ -963,10 +971,9 @@ paths:
         flow tab. Does not mutate Node-RED until an admin with `*` approves.
 
         Include `expectedRev` (preferred; `expected_rev` accepted as alias)
-        from the latest `GET /flows` or `GET /flows/{id}` response. The live
-        flow revision is checked **at submit time** (**409**
-        `version_mismatch` if stale). On approve, a stale revision marks the
-        proposal `rejected` with a resubmit message (no deploy).
+        from `GET /flows` or `GET /flows/{id}`. Recent known stale revisions are
+        accepted using snapshot history and rebased immediately. Unknown revisions
+        return **409** `version_mismatch`. Approval rechecks against the live revision.
 
         Optional `title` (≤80 chars) is stored as a human-friendly label; when
         omitted it is auto-generated from the change set. Responses always
@@ -1055,14 +1062,18 @@ paths:
         (long text fields listed for expandable UI). Modified nodes include
         line-level diffs for text fields such as `func` and `template`.
 
-        `baseRevStale` is true only for **pending** proposals when
-        `expectedRev` does not match the live revision (approve would fail).
-        Approved/rejected/failed proposals never set `baseRevStale`. When
-        pending and stale, `vsCurrent` optionally includes proposal-vs-live
-        sections for review.
-
-        Admins with `read` can diff any proposal. Access-link clients can only
-        diff proposals they created.
+        `baseRev` aliases `expectedRev`, the stored proposal base revision.
+        `baseRevChanged` is true only for **open** proposals when
+        `expectedRev` does not match the live revision (informational).
+        This is informational after a successful rebase, not an approval error.
+        `rebase.state` (`clean`, `merged`, `conflict`) reports merge readiness and
+        `rebase.rev` identifies the checked live rev. Closed proposals never set
+        `baseRevChanged` as true. Open proposals include
+        `rebase` and `liveChanges` (editor changes since the stored base).
+        Without conflicts, `vsCurrent` compares the merged deployment to live.
+        Merges use raw stored proposals and live flows; AI diff sections are redacted.
+
+        Admins with `read` and access-link clients can diff any proposal.
       operationId: getProposalDiff
       security:
         - AccessLinkBearer: []
@@ -1085,6 +1096,102 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /proposals/{id}/resolve-conflict:
+    post:
+      tags: [Proposals]
+      summary: Choose live or proposed for one current conflict, or undo the latest choice
+      operationId: resolveProposalConflict
+      security:
+        - AdminSession: []
+      parameters:
+        - $ref: '#/components/parameters/ProposalId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ConflictChoiceRequest'
+      responses:
+        '200':
+          description: Presented proposal with current rebase metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proposal'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Proposal not found
+        '409':
+          description: Proposal closed, conflict missing, or revision unavailable
+  /proposals/{id}/recheck:
+    post:
+      tags: [Proposals]
+      summary: Recheck an open proposal against raw live flows
+      operationId: recheckProposal
+      security:
+        - AdminSession: []
+      parameters:
+        - $ref: '#/components/parameters/ProposalId'
+      responses:
+        '200':
+          description: Presented proposal with current rebase metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proposal'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Proposal not found
+        '409':
+          description: Proposal closed, conflict missing, or revision unavailable
+  /proposals/{id}/resolve:
+    post:
+      tags: [Proposals]
+      summary: Resolve your own open proposal with a choice or replacement payload
+      description: |
+        Use nodeId + choice for one current conflict (overlapping fields only;
+        independent live and proposed edits survive). Or use expectedRev + payload:
+        operations apply to the flow snapshot at expectedRev, not the stored
+        proposal or merged result. Include every intended edit. Do not mix modes.
+      operationId: resolveProposal
+      security:
+        - AccessLinkBearer: []
+      parameters:
+        - $ref: '#/components/parameters/ProposalId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ResolveProposalRequest'
+      responses:
+        '200':
+          description: Presented proposal with current rebase metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proposal'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Proposal not found
+        '409':
+          description: Proposal closed, conflict missing, or revision unavailable
+
   /proposals/{id}/approve:
     post:
       tags: [Proposals]
@@ -1094,9 +1201,12 @@ paths:
         Optional body `deploymentType`: `nodes` (default from settings),
         `flows`, or `full`.
 
-        Revision conflict: proposal is marked `rejected` with a resubmit
-        message (HTTP 200 with `status: rejected`). Other deploy errors mark
-        it `failed`. Concurrent approve of the same id returns 409.
+        Auto-rebases against raw live flows and deploys the merged tab with the live rev.
+        Conflicts return 409 `proposal_conflict` with field-name-only `conflicts`.
+        Merged editor changes require `mergedHash` from the reviewed diff; otherwise
+        409 `rebase_ack_required` includes the current hash. Revision races retry
+        up to three times then return 409 `rebase_race`, leaving the proposal open.
+        Other deploy errors mark it `failed`. Concurrent approval returns 409.
       operationId: approveProposal
       security:
         - AdminSession: []
@@ -1179,14 +1289,16 @@ paths:
   /proposals/{id}/withdraw:
     post:
       tags: [Proposals]
-      summary: Withdraw own pending proposal
+      summary: Withdraw an open proposal (owner token or full admin recovery)
       description: |
-        Access-link Bearer only. Withdraws a **pending** proposal created by
-        this token. Status becomes `withdrawn` (not `rejected`). Optional
+        Accepts the creating access-link Bearer, or a full (`*`) admin session
+        for lost-token recovery. Other tokens and read-only admins are forbidden.
+        Withdraws an **open** (pending or conflict) proposal. Status becomes `withdrawn` (not `rejected`). Optional
         JSON body `{ "reason": "…" }`.
       operationId: withdrawProposal
       security:
         - AccessLinkBearer: []
+        - AdminSession: []
       parameters:
         - $ref: '#/components/parameters/ProposalId'
       requestBody:
@@ -1208,7 +1320,7 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Not owned by this access link
+          description: Not owned by this access link or admin lacks full permission
           content:
             application/json:
               schema:
@@ -1369,8 +1481,8 @@ components:
                 code: access_link_invalid
     VersionConflict:
       description: |
-        `expectedRev` does not match the current flow revision
-        (`code: version_mismatch`). Re-read flows and resubmit.
+        `expectedRev` is unavailable in recent snapshot history and does not
+        match the live revision (`code: version_mismatch`). Re-read flows and resubmit.
       content:
         application/json:
           schema:
@@ -1456,6 +1568,14 @@ components:
       description: |
         Machine-readable `code` on JSON error bodies. See docs/errors.md.
 
+        - `approve_queue_timeout` (504): Approval exceeded its queue-wait deadline (default 60 seconds); no deployment was started for this request
+        - `deploy_timeout` (504): Deployment exceeded its deadline (default 60 seconds); approvals wait for settlement or the hard cap (default 5 minutes)
+        - `proposal_conflict` (409): Editor and proposal changes conflict (conflicts contains field names only)
+        - `rebase_ack_required` (409): The merged result needs review (mergedHash included)
+        - `rebase_race` (409): Flows kept changing during approval
+        - `conflict_not_found` (409): The requested conflict no longer exists
+        - `invalid_choice` (400): Invalid manual conflict choice
+        - `flow_id_mismatch` (400): Resolution tried to change the proposal flow id
         - `access_link_missing` (401): No Bearer / path token
         - `bearer_scheme_required` (401): Auth used Basic (or non-Bearer)
         - `token_expired` (401): Known token past `expiresAt` (body includes `expiredAt` and `accessLinksUrl`)
@@ -1481,10 +1601,10 @@ components:
         - `invalid_diff_format` (400): Unknown `format` on proposal diff
         - `confirm_required` (400): GET withdraw without `confirm=1`
         - `missing_expected_rev` (400): Proposal submitted without `expectedRev` / `rev`
-        - `version_mismatch` (409): Stale `rev` / `expectedRev`
+        - `version_mismatch` (409): Unknown or unavailable `rev` / `expectedRev` snapshot
         - `proposal_not_found` (404): Unknown proposal id
-        - `proposal_not_pending` (409): Action needs a pending proposal
-        - `proposal_not_owned` (403): Withdraw of another token’s proposal
+        - `proposal_not_pending` (409): Action needs an open proposal
+        - `proposal_not_owned` (403): Resolve or withdraw another token’s proposal
         - `validation_failed` (400): Several validation errors at once (message `N validation errors`)
         - `duplicate_node_id` (400): The same node id appears more than once in a full tab or batch
         - `missing_node_id` (400): Node / op without an id
@@ -1509,6 +1629,14 @@ components:
         - `upstream_error` (502): Node-RED runtime/flows error
         - `internal_error` (500): Unexpected server error
       enum:
+        - approve_queue_timeout
+        - deploy_timeout
+        - proposal_conflict
+        - rebase_ack_required
+        - rebase_race
+        - conflict_not_found
+        - invalid_choice
+        - flow_id_mismatch
         - access_link_missing
         - bearer_scheme_required
         - token_expired
@@ -1737,6 +1865,11 @@ components:
     AiAccessSettingsPatch:
       type: object
       properties:
+        proposalTtlDays:
+          type: integer
+          minimum: 1
+          maximum: 365
+          default: 7
         enabled:
           type: boolean
         allowWithoutAdminAuth:
@@ -2184,9 +2317,46 @@ components:
             additionalProperties: true
       additionalProperties: true
 
+    ProposalRebase:
+      type: object
+      description: Merge metadata; conflicts contain field names only, never field values.
+      properties:
+        state:
+          type: string
+          enum: [clean, merged, conflict]
+        rev:
+          type: string
+        mergedHash:
+          type: string
+        conflicts:
+          type: array
+          items:
+            type: object
+            properties:
+              nodeId:
+                type: string
+              kind:
+                type: string
+              fields:
+                type: array
+                items:
+                  type: string
+              message:
+                type: string
+              choices:
+                type: array
+                items:
+                  type: string
+                  enum: [live, proposed]
+        liveChangedCount:
+          type: integer
+        checkedAt:
+          type: string
+          format: date-time
+
     ProposalStatus:
       type: string
-      enum: [pending, approved, rejected, failed, withdrawn, expired, superseded]
+      enum: [pending, conflict, approved, rejected, failed, withdrawn, expired, superseded]
 
     Proposal:
       type: object
@@ -2195,6 +2365,7 @@ components:
         - type
         - status
         - expectedRev
+        - baseRev
         - payload
         - createdBy
         - createdAt
@@ -2204,6 +2375,30 @@ components:
         - reviewUrl
         - reviewPath
       properties:
+        conflictChoice:
+          type: object
+          description: Latest manual resolution; admins can undo it until the next body edit or choice. Undo snapshots are never returned.
+          required: [nodeId, choice]
+          properties:
+            nodeId:
+              type: string
+            choice:
+              type: string
+              enum: [live, proposed]
+        deployPending:
+          type: object
+          description: Timed-out deployment has an unknown outcome; approvals wait until settlement or the hard cap. Check live flows before approving again.
+          required: [mergedHash, reason]
+          properties:
+            mergedHash:
+              type: string
+            reason:
+              type: string
+            queueReleased:
+              type: boolean
+              description: True when the deploy hard cap released the queue. Late settlement no longer updates this proposal; approval always re-reads live flows.
+        rebase:
+          $ref: '#/components/schemas/ProposalRebase'
         id:
           type: string
         type:
@@ -2213,6 +2408,12 @@ components:
           $ref: '#/components/schemas/ProposalStatus'
         expectedRev:
           type: string
+        baseRev:
+          type: string
+          description: Revision of the stored base snapshot; alias of expectedRev.
+        baseRevChanged:
+          type: boolean
+          description: Informational revision difference for open proposals; use rebase.state for merge readiness.
         payload:
           $ref: '#/components/schemas/ReplaceFlowPayload'
         baseFlow:
@@ -2318,9 +2519,8 @@ components:
         reason:
           type: string
           description: |
-            Present when rejected, failed, or withdrawn. On revision conflict
-            after approve, explains that expectedRev is stale and the AI should
-            re-read flows and submit a new proposal.
+            Present when rejected, failed, withdrawn, or expired. Revision changes
+            keep open proposals pending or in conflict; they do not close them.
         resultRev:
           type: string
 
@@ -2372,7 +2572,7 @@ components:
       type: object
       required: [kind]
       description: |
-        Admin for approve/reject/fail; access-link for withdraw.
+        Admin for approve/reject/fail and recovery withdrawal; access-link for owner withdrawal.
       properties:
         kind:
           type: string
@@ -2424,9 +2624,59 @@ components:
               find: Hello
               replace: Hi
 
+    ConflictChoiceRequest:
+      type: object
+      required: [nodeId, choice]
+      properties:
+        nodeId:
+          type: string
+        choice:
+          type: string
+          enum: [live, proposed, undo]
+          description: Undo restores the proposal before the latest choice for nodeId and rechecks against live. Available until the next body edit or choice; admin only. Nothing is deployed.
+
+    ResolveProposalRequest:
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [nodeId, choice]
+          properties:
+            nodeId:
+              type: string
+              description: Current conflict node id; flow id for tab/env conflicts.
+            choice:
+              type: string
+              enum: [live, proposed]
+              description: Keep this side for overlapping fields only; preserve independent changes and live secrets.
+        - type: object
+          required: [expectedRev]
+          properties:
+            expectedRev:
+              type: string
+              description: Flow snapshot revision to which replacement operations apply.
+            title:
+              type: string
+              maxLength: 80
+            payload:
+              $ref: '#/components/schemas/ReplaceFlowPayload'
+              description: Complete intended edits based on expectedRev; not applied to the stored proposal or merged result.
+            nodes:
+              type: array
+              description: Legacy alias for replacement payload nodes, applied to expectedRev.
+              items:
+                type: object
+                additionalProperties: true
+          not:
+            anyOf:
+              - required: [nodeId]
+              - required: [choice]
+
     ApproveProposalRequest:
       type: object
       properties:
+        mergedHash:
+          type: string
+          description: Hash of the reviewed merged result; required when editor changes are merged.
         deploymentType:
           $ref: '#/components/schemas/DeploymentType'
 
@@ -2536,6 +2786,11 @@ components:
       type: object
       required: [summary, added, removed, modified]
       properties:
+        tabProperties:
+          type: array
+          description: Before and after values of changed flow settings, including env. Uses the caller's redacted view.
+          items:
+            $ref: '#/components/schemas/ProposalDiffPropertyChange'
         summary:
           type: object
           required: [added, removed, modified, tabChanges]
@@ -2572,7 +2827,8 @@ components:
             - flowId
             - expectedRev
             - currentRev
-            - baseRevStale
+            - baseRevChanged
+            - baseRev
             - compareAgainst
           properties:
             proposalId:
@@ -2581,12 +2837,15 @@ components:
               type: string
             expectedRev:
               type: string
+            baseRev:
+              type: string
+              description: Alias of expectedRev, the stored base revision.
             currentRev:
               type: string
-            baseRevStale:
+            baseRevChanged:
               type: boolean
               description: |
-                True only for pending proposals when expectedRev ≠ live rev.
+                Informational: true for open proposals when expectedRev ≠ live rev.
                 Never true for approved/rejected/failed.
             compareAgainst:
               type: string
@@ -2594,10 +2853,34 @@ components:
             baseSnapshotMissing:
               type: boolean
               description: True for legacy proposals without a stored baseFlow
+            rebase:
+              $ref: '#/components/schemas/ProposalRebase'
+            conflictValues:
+              type: array
+              description: Base, live and proposed values for each conflicting path. AI callers receive redacted values.
+              items:
+                type: object
+                required: [nodeId, fields]
+                properties:
+                  nodeId:
+                    type: string
+                  fields:
+                    type: array
+                    items:
+                      type: object
+                      required: [field]
+                      properties:
+                        field:
+                          type: string
+                        base: {}
+                        live: {}
+                        proposed: {}
+            liveChanges:
+              $ref: '#/components/schemas/ProposalDiffSections'
             vsCurrent:
               $ref: '#/components/schemas/ProposalDiffSections'
               description: |
-                Present when pending and baseRevStale — proposal vs live flow.
+                Present for open proposals without conflicts — merged result vs live flow.
 
     AuditActor:
       oneOf:

package/docs/errors.md

@@ -13,6 +13,14 @@ GET-link `401` responses include a `WWW-Authenticate: Bearer …` header.
 
 | Code | HTTP | Meaning | Hint / next step | Channels |
 | --- | --- | --- | --- | --- |
+| `approve_queue_timeout` | 504 | Approval exceeded its queue-wait deadline (default 60 seconds); no deployment was started for this request | Check the live flow and retry approval | admin |
+| `deploy_timeout` | 504 | Deployment exceeded its deadline (default 60 seconds); approvals wait for settlement or the hard cap (default 5 minutes) | Before the cap, late settlement updates the proposal; after the cap, deployPending.queueReleased is true and the outcome stays unknown. Check the live flow before approving again; approval always re-reads live | admin |
+| `proposal_conflict` | 409 | Editor and proposal changes conflict (conflicts contains field names only) | Read the current flow and resolve the proposal before approval | GET, REST, MCP, admin |
+| `rebase_ack_required` | 409 | The merged result needs review (mergedHash included) | Review the diff and approve with its mergedHash | admin |
+| `rebase_race` | 409 | Flows kept changing during approval | Recheck the proposal and retry approval | admin |
+| `conflict_not_found` | 409 | The requested conflict no longer exists | Reload the proposal and its conflicts | REST, MCP, admin |
+| `invalid_choice` | 400 | Invalid manual conflict choice | Use nodeId plus an available live or proposed choice, without replacement payload or revision | REST, MCP, admin |
+| `flow_id_mismatch` | 400 | Resolution tried to change the proposal flow id | Keep the same flowId or submit a new proposal | REST, MCP |
 | `access_link_missing` | 401 | No Bearer / path token | Ask the user for a new access link of the right kind | GET, REST, MCP |
 | `bearer_scheme_required` | 401 | Auth used Basic (or non-Bearer) | Send `Authorization: Bearer <token>` | REST, MCP |
 | `token_expired` | 401 | Known token past `expiresAt` (body includes `expiredAt` and `accessLinksUrl`) | Ask the user to create a new link on the `/ai-access` dashboard → Access tokens (`accessLinksUrl`) | GET, REST, MCP |
@@ -38,10 +46,10 @@ GET-link `401` responses include a `WWW-Authenticate: Bearer …` header.
 | `invalid_diff_format` | 400 | Unknown `format` on proposal diff | Use `format=summary` (default) or `format=full` | GET, REST, MCP |
 | `confirm_required` | 400 | GET withdraw without `confirm=1` | Repeat the request with `confirm=1` | GET |
 | `missing_expected_rev` | 400 | Proposal submitted without `expectedRev` / `rev` | Read the flow and pass its `rev` | GET, REST, MCP |
-| `version_mismatch` | 409 | Stale `rev` / `expectedRev` | Re-read flows and resubmit | GET, REST, MCP |
+| `version_mismatch` | 409 | Unknown or unavailable `rev` / `expectedRev` snapshot | Re-read flows and resubmit | GET, REST, MCP |
 | `proposal_not_found` | 404 | Unknown proposal id | List proposals and use an existing id | GET, REST, MCP |
-| `proposal_not_pending` | 409 | Action needs a pending proposal | Only pending can withdraw / decide | GET, REST, MCP |
-| `proposal_not_owned` | 403 | Withdraw of another token’s proposal | Only the creating token can withdraw | GET, REST, MCP |
+| `proposal_not_pending` | 409 | Action needs an open proposal | Only pending or conflict proposals can withdraw / decide | GET, REST, MCP |
+| `proposal_not_owned` | 403 | Resolve or withdraw another token’s proposal | Use the creating token; lost-token withdrawal requires a full admin session | GET, REST, MCP |
 | `validation_failed` | 400 | Several validation errors at once (message `N validation errors`) | Fix every entry in errors[] and resubmit. | GET, REST, MCP |
 | `duplicate_node_id` | 400 | The same node id appears more than once in a full tab or batch | Give every node a unique id | GET, REST, MCP |
 | `missing_node_id` | 400 | Node / op without an id | Include a non-empty string id | GET, REST, MCP |
@@ -72,6 +80,8 @@ Returned in `warnings[]` on a successful propose/submit; they never block.
 
 | Code | HTTP | Meaning | Hint / next step | Channels |
 | --- | --- | --- | --- | --- |
+| `duplicate_env_keys` | 200 | Changed env arrays contain duplicate names; pairing by name is ambiguous when entries are reordered | Review the env values before approval | GET, REST, MCP, admin |
+| `secret_may_revert` | 200 | Secret spans could not be aligned during proposed conflict resolution; proposed values were kept | Review the warned field against live flows before approval; an editor secret change may be reverted | GET, REST, MCP, admin |
 | `missing_config_node` | 201 | Warning: node has no (or an unresolved) config node yet | Configure before deploy if needed; see `candidates` | GET, REST, MCP |
 | `unwired_node` | 201 | Warning: node has outputs but no wires | Wire it, or ignore while scaffolding | GET, REST, MCP |
 | `incomplete_wires` | 201 | Warning: fewer wire ports than outputs | Add ports if outputs should connect | GET, REST, MCP |
@@ -83,9 +93,10 @@ Returned in `warnings[]` on a successful propose/submit; they never block.
 | `secret_tab_changed` | 201 | Warning: proposal with restored secrets also changes other nodes in the tab | Review every change before approving | GET, REST, MCP |
 | `secret_reference_added` | 201 | Warning: an added/changed node now reads a secret-named env/global/flow value (env.get, $env, ${…}, typed input) | Reviewer must check the value is not sent anywhere unexpected | GET, REST, MCP |
 
-## Auto-closed proposal statuses
+## Proposal statuses
 
 | Code | HTTP | Meaning | Hint / next step | Channels |
 | --- | --- | --- | --- | --- |
-| `expired` | 200 | Status: pending proposal auto-closed because the live flow rev moved past `expectedRev` | Re-read the flow and submit a new proposal | GET, REST, MCP |
-| `superseded` | 200 | Status: pending proposal auto-closed because another proposal on the same flow was approved | Re-read the flow and submit a new proposal if still needed | GET, REST, MCP |
+| `conflict` | 200 | Status: open proposal has conflicting editor changes; approval blocked | Read the current flow and resolve the proposal | GET, REST, MCP |
+| `expired` | 200 | Status: open proposal expired after the configured TTL (default 7 days) | Re-read the flow and submit a new proposal | GET, REST, MCP |
+| `superseded` | 200 | Legacy closed status; new approvals rebase other open proposals | Re-read the flow and submit a new proposal if still needed | GET, REST, MCP |