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

package/dist/plugin.d.cts

@@ -217,7 +217,29 @@ declare class AuditLog {
  * Proposal JSON store under `.ai-access/proposals/`.
  */
 
-type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'failed' | 'withdrawn' | 'expired' | 'superseded';
+type ProposalStatus = 'pending' | 'conflict' | 'approved' | 'rejected' | 'failed' | 'withdrawn' | 'expired' | 'superseded';
+/** One stored rebase conflict (field names only — never values). */
+interface StoredRebaseConflict {
+    kind: string;
+    nodeId?: string;
+    nodeType?: string;
+    nodeName?: string;
+    fields?: string[];
+    message: string;
+    choices: ('live' | 'proposed')[];
+}
+/** Result of the last auto-rebase check against the live flows. */
+interface ProposalRebaseInfo {
+    /** Live rev the check ran against. */
+    rev: string;
+    state: 'clean' | 'merged' | 'conflict';
+    /** Hash of the tab approve would deploy (absent on conflict). */
+    mergedHash?: string;
+    conflicts: StoredRebaseConflict[];
+    /** Nodes (or the tab) changed live since the base snapshot. */
+    liveChangedCount: number;
+    checkedAt: string;
+}
 type ProposalType = 'replace_flow';
 interface AccessLinkProposalCreator {
     kind: 'access-link';
@@ -273,6 +295,14 @@ interface Proposal {
         nodeId: string;
         property: string;
     }[];
+    /** Persisted while a timed-out runtime deployment has an unknown outcome. */
+    deployPending?: {
+        mergedHash: string;
+        reason: string;
+        queueReleased?: boolean;
+    };
+    /** Last auto-rebase result (pending / conflict proposals). */
+    rebase?: ProposalRebaseInfo;
     /**
      * Short human title (≤80 chars). Set at submit (AI-supplied or auto-generated).
      * Optional on legacy proposals; API responses always resolve a title.
@@ -329,15 +359,38 @@ declare class ProposalStore {
      */
     beginApprove(id: string): Proposal;
     releaseLock(id: string): void;
+    recordDeployPending(id: string, pending: Proposal['deployPending']): Proposal;
     markApproved(id: string, decidedBy: ProposalDecisionBy, resultRev: string): Proposal;
     markRejected(id: string, decidedBy: ProposalDecisionBy | undefined, reason: string): Proposal;
     markFailed(id: string, decidedBy: ProposalDecisionBy | undefined, reason: string): Proposal;
     markWithdrawn(id: string, decidedBy: ProposalDecisionBy, reason: string): Proposal;
     /**
      * Auto-close a pending proposal that can no longer be approved
-     * (`expired` = live rev moved; `superseded` = another proposal was approved).
+     * (`expired` = pending longer than the proposal TTL).
      */
     markClosed(id: string, status: 'expired' | 'superseded', reason: string, decidedBy?: ProposalDecisionBy): Proposal;
+    /**
+     * Store the latest rebase check and flip `pending` ↔ `conflict`.
+     * No-op (no write) when nothing changed. Skips decided or in-flight records.
+     */
+    recordRebase(id: string, info: ProposalRebaseInfo): Proposal;
+    /**
+     * Replace an open proposal's base snapshot and/or body (conflict resolution).
+     * Status returns to `pending`; the caller re-runs the rebase.
+     */
+    updateBody(id: string, update: {
+        baseFlow: Partial<FlowTab>;
+        flow: Partial<FlowTab>;
+        expectedRev?: string;
+        title?: string;
+        restoredSecrets?: {
+            nodeId: string;
+            property: string;
+        }[];
+        warnings?: ProposalWarning[];
+    }): Proposal;
+    /** True while an approve holds this proposal's lock. */
+    isApproving(id: string): boolean;
 }
 
 /**
@@ -357,6 +410,7 @@ interface PersistedAiAccessSettings {
     enabled?: boolean;
     allowWithoutAdminAuth?: boolean;
     defaultLinkTtlSeconds?: number;
+    proposalTtlDays?: number;
     defaultDeploymentType?: DeploymentType;
     maxActiveLinks?: number;
     publicBaseUrl?: string;
@@ -378,6 +432,7 @@ interface EffectiveAiAccessSettings {
     enabled: boolean;
     allowWithoutAdminAuth: boolean;
     defaultLinkTtlSeconds: number;
+    proposalTtlDays: number;
     defaultDeploymentType: DeploymentType;
     maxActiveLinks: number;
     publicBaseUrl: string;
@@ -463,15 +518,32 @@ type CatalogueFetcher = (url: string, etag?: string) => Promise<{
  * Approve / reject proposals through the FlowAdapter with audit logging.
  */
 
+interface ProposalServiceOptions {
+    /** Maximum time to await updateFlow (default 60 seconds). Does not cancel the runtime operation. */
+    deployTimeoutMs?: number;
+    /** Maximum time waiting to start approval (default 60 seconds). */
+    approveQueueTimeoutMs?: number;
+    /** Release the queue after this much unsettled deployment time (default 5 minutes). */
+    deployHardCapMs?: number;
+}
+interface ApproveOptions {
+    deploymentType?: DeploymentType;
+    /**
+     * `mergedHash` the reviewer last saw. Required when the rebase merged live
+     * changes into the proposal; when supplied it must match the current merge.
+     */
+    mergedHash?: string;
+}
 declare class ProposalService {
     private readonly proposals;
     private readonly audit;
     private readonly adapter;
     private readonly getDeploymentType;
-    constructor(proposals: ProposalStore, audit: AuditLog, adapter: FlowAdapter, getDeploymentType: () => DeploymentType);
-    approve(id: string, decidedBy: ProposalDecisionBy, options?: {
-        deploymentType?: DeploymentType;
-    }): Promise<Proposal>;
+    private readonly serviceOptions;
+    constructor(proposals: ProposalStore, audit: AuditLog, adapter: FlowAdapter, getDeploymentType: () => DeploymentType, serviceOptions?: ProposalServiceOptions);
+    approve(id: string, decidedBy: ProposalDecisionBy, options?: ApproveOptions): Promise<Proposal>;
+    private approveLocked;
+    private withDeployDeadline;
     reject(id: string, decidedBy: ProposalDecisionBy, reason: string): Proposal;
 }
 
@@ -495,10 +567,17 @@ interface AiAccessSettings {
     allowWithoutAdminAuth?: boolean;
     /** Default access-link TTL in seconds (default: 14400 = 4h). */
     defaultLinkTtlSeconds?: number;
+    proposalTtlDays?: number;
     /** Maximum concurrent active access links (default: 10). */
     maxActiveLinks?: number;
     /** Deployment type used when approving proposals (default: nodes). */
     defaultDeploymentType?: 'nodes' | 'flows' | 'full';
+    /** Approval queue waiting deadline in milliseconds (default 60,000). */
+    approveQueueTimeoutMs?: number;
+    /** Deployment caller deadline in milliseconds (default 60,000). */
+    deployTimeoutMs?: number;
+    /** Release an unsettled deployment's approval queue after this duration (default 300,000 ms). */
+    deployHardCapMs?: number;
     /**
      * Rate-limit window in milliseconds for `/mcp/api` and `/mcp/a`
      * (default: 60000).
@@ -643,6 +722,7 @@ interface NodeRedPluginAPI {
     };
     events?: {
         on(event: string, listener: () => void): void;
+        removeListener?(event: string, listener: () => void): void;
     };
     auth: NodeRedAuthAPI;
     plugins: {

package/docs/api/openapi.yaml

@@ -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,10 +184,10 @@ 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.
+    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
 
@@ -963,10 +963,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 +1054,14 @@ 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.
+        `baseRevStale` is true only for **open** proposals when
+        `expectedRev` does not match the live revision (informational).
+        Closed proposals never set `baseRevStale`. 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` can diff any proposal. Access-link clients can only
-        diff proposals they created.
+        Admins with `read` and access-link clients can diff any proposal.
       operationId: getProposalDiff
       security:
         - AccessLinkBearer: []
@@ -1085,6 +1084,97 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /proposals/{id}/resolve-conflict:
+    post:
+      tags: [Proposals]
+      summary: Choose live or proposed for one current conflict
+      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 fresh payload
+      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 +1184,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: []
@@ -1181,7 +1274,7 @@ paths:
       tags: [Proposals]
       summary: Withdraw own pending proposal
       description: |
-        Access-link Bearer only. Withdraws a **pending** proposal created by
+        Access-link Bearer only. Withdraws an **open** (pending or conflict) proposal created by
         this token. Status becomes `withdrawn` (not `rejected`). Optional
         JSON body `{ "reason": "…" }`.
       operationId: withdrawProposal
@@ -1369,8 +1462,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 +1549,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,9 +1582,9 @@ 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_pending` (409): Action needs an open proposal
         - `proposal_not_owned` (403): Withdraw of 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
@@ -1509,6 +1610,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 +1846,11 @@ components:
     AiAccessSettingsPatch:
       type: object
       properties:
+        proposalTtlDays:
+          type: integer
+          minimum: 1
+          maximum: 365
+          default: 7
         enabled:
           type: boolean
         allowWithoutAdminAuth:
@@ -2184,9 +2298,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
@@ -2204,6 +2355,20 @@ components:
         - reviewUrl
         - reviewPath
       properties:
+        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:
@@ -2318,9 +2483,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
 
@@ -2424,9 +2588,39 @@ components:
               find: Hello
               replace: Hi
 
+    ConflictChoiceRequest:
+      type: object
+      required: [nodeId, choice]
+      properties:
+        nodeId:
+          type: string
+        choice:
+          type: string
+          enum: [live, proposed]
+
+    ResolveProposalRequest:
+      type: object
+      required: [expectedRev]
+      properties:
+        expectedRev:
+          type: string
+        title:
+          type: string
+          maxLength: 80
+        payload:
+          $ref: '#/components/schemas/ReplaceFlowPayload'
+        nodes:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+
     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'
 
@@ -2586,7 +2780,7 @@ components:
             baseRevStale:
               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 +2788,14 @@ components:
             baseSnapshotMissing:
               type: boolean
               description: True for legacy proposals without a stored baseFlow
+            rebase:
+              $ref: '#/components/schemas/ProposalRebase'
+            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 | admin |
+| `invalid_choice` | 400 | Invalid manual conflict choice | Use an available live or proposed choice | 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,9 +46,9 @@ 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_pending` | 409 | Action needs an open proposal | Only pending or conflict proposals 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 |
 | `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 |
@@ -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 |