{"record":{"id":"d0d0a1efdefa24d8","repo":"paperclipai/paperclip","slug":"expected-acpx-permission-mode-is-invalid","errorCode":null,"errorMessage":"Expected ACPX permission mode is invalid","messagePattern":"Expected ACPX permission mode is invalid","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts","lineNumber":261,"sourceCode":"    expected.acpxRecordId,\n    expected.backendSessionId,\n    expected.agentSessionId,\n    expected.requestedModel,\n    expected.effectiveModel,\n  ]) {\n    validateIdentity(value, \"expected ACPX\");\n  }\n  if (\n    !isDigest(expected.profileDigest) ||\n    !isDigest(expected.workspaceDigest)\n  ) {\n    throw new Error(\"Expected ACPX identity digest is invalid\");\n  }\n  if (\n    expected.permissionMode !== undefined &&\n    !isPermissionMode(expected.permissionMode)\n  ) {\n    throw new Error(\"Expected ACPX permission mode is invalid\");\n  }\n  validateFenceCandidates(expected.providerLifetimeFenceCandidates);\n}\n\nfunction validateFenceCandidates(\n  value: unknown,\n): asserts value is readonly [number, number, number] {\n  if (\n    !Array.isArray(value) ||\n    value.length !== 3 ||\n    value.some(\n      (port) => !Number.isSafeInteger(port) || port < 49_152 || port > 65_535,\n    ) ||\n    new Set(value).size !== 3\n  ) {\n    throw new Error(\"ACPX provider lifetime fence candidates are invalid\");\n  }\n}","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts#L243-L279","documentation":"validateExpected validates the caller-supplied expected session identity used for recovery. Unlike the persisted-record check, permissionMode is optional here; the error is thrown only when the caller provides one that is not a recognized permission mode. This catches bad values passed by the caller rather than corruption in the stored record.","triggerScenarios":"Calling verifyExpectedAcpxIdentity (directly or via open()/acpxProviderSessionIdentity()) with expected.permissionMode defined but not matching isPermissionMode — e.g. misspelled mode, wrong casing, or a mode from another driver's vocabulary.","commonSituations":"Configuring recovery in code with a mode string like \"BYPASS\" or \"bypass\" instead of the exact enum value; copying option names from a different agent adapter; dynamic config where a raw CLI string is passed through unvalidated.","solutions":["Use one of the library's exact permission mode strings for expected.permissionMode.","Omit permissionMode from the expected identity if you do not need to constrain recovery — it is optional.","Validate the mode against the same isPermissionMode predicate your code uses before calling verifyExpectedAcpxIdentity."],"exampleFix":"// before\nverifyExpectedAcpxIdentity(expected, record); // expected.permissionMode = \"BYPASS\"\n// after\nverifyExpectedAcpxIdentity({ ...expected, permissionMode: \"bypassAll\" }, record); // exact enum value","handlingStrategy":"validation","validationCode":"if (expected.permissionMode !== undefined && !KNOWN_PERMISSION_MODES.includes(expected.permissionMode)) {\n  throw new Error(`Invalid expected permissionMode: ${expected.permissionMode}`);\n}","typeGuard":"const isKnownMode = (v: unknown): v is PermissionMode =>\n  typeof v === \"string\" && [\"default\", \"acceptEdits\", \"bypassAll\"].includes(v);","tryCatchPattern":"try {\n  verifyExpectedAcpxIdentity(expected, record);\n} catch (e) {\n  if (e.message === \"Expected ACPX permission mode is invalid\") {\n    return verifyExpectedAcpxIdentity({ ...expected, permissionMode: undefined }, record);\n  }\n  throw e;\n}","preventionTips":["Use the library's exported permission mode constants instead of raw strings.","Omit permissionMode from expected identity when unconstrained.","Centralize permission mode strings in one typed constant module."],"tags":["validation","enum","argument","acpx"],"backgroundTag":"invalid-enum-argument","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}