{"record":{"id":"a45b4d5857624ace","repo":"paperclipai/paperclip","slug":"native-session-multi-run-unavailable","errorCode":"native_session_multi_run_unavailable","errorMessage":"native_session_multi_run_unavailable","messagePattern":"native_session_multi_run_unavailable","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/backends/harness-driver-backend.ts","lineNumber":479,"sourceCode":"      threadLineage: this.#session.lineage !== undefined,\n    };\n  }\n\n  async attachRun(input: {\n    identity: OpenNativeSessionInput[\"identity\"];\n  }): Promise<void> {\n    this.#assertProtocolIntegrity();\n    const currentIdentity = this.#input.identity;\n    if (\n      input.identity.sessionId !== currentIdentity.sessionId ||\n      input.identity.companyId !== currentIdentity.companyId ||\n      input.identity.issueId !== currentIdentity.issueId ||\n      input.identity.agentId !== currentIdentity.agentId\n    ) {\n      throw new Error(\"native_session_attach_binding_mismatch\");\n    }\n    if (this.#session.attachRun === undefined) {\n      throw new Error(\"native_session_multi_run_unavailable\");\n    }\n    try {\n      await this.#session.attachRun({ runId: input.identity.runId });\n      this.#assertProtocolIntegrity();\n    } catch (error) {\n      this.#rethrowProtocolIntegrity(error);\n      throw error;\n    }\n    this.#input = { ...this.#input, identity: structuredClone(input.identity) };\n    this.#terminal = null;\n    this.#explicitlyCancelled = false;\n  }\n\n  async detachControllerForRestart(): Promise<void> {\n    if (this.#session.detachControllerForRestart === undefined) return;\n    await this.#session.detachControllerForRestart();\n  }\n","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/backends/harness-driver-backend.ts#L461-L497","documentation":"attachRun is an optional capability on a HarnessSession. After identity binding succeeds, the backend checks whether the underlying session implements attachRun; if it is undefined, the session driver does not support multi-run attachment and this error is thrown. It signals a driver capability gap, not a caller mistake in identity.","triggerScenarios":"Calling attachRun on a native session whose driver only supports a single run per session (session.attachRun === undefined). Typical with harness drivers that lack the multi-run protocol extension.","commonSituations":"Using an older agent adapter or driver version that predates multi-run support; a driver built before the attachRun protocol method was added; calling attachRun on a backend created from a session factory that never wires attachRun.","solutions":["Check the driver/adapter version and upgrade to one that implements attachRun","If the driver is up to date, start a new session per run instead of attaching multiple runs to one session","Feature-check before calling: if (session.attachRun === undefined) fall back to a fresh session"],"exampleFix":"// before\nawait backend.attachRun({ identity });\n// after\nif (!backend.supportsMultiRun()) {\n  backend = await createNativeSessionBackend({ identity });\n} else {\n  await backend.attachRun({ identity });\n}","handlingStrategy":"fallback","validationCode":"if (backend.supportsMultiRun?.() === false) { startFreshSession(); }","typeGuard":"const multiRunSupported = typeof (session as HarnessSession).attachRun === 'function';","tryCatchPattern":"try { await backend.attachRun({ identity }); } catch (e) { if (e.message === 'native_session_multi_run_unavailable') { backend = await createNativeSessionBackend({ identity }); } else throw e; }","preventionTips":["Feature-detect attachRun before using multi-run","Keep driver/adapter versions current with the protocol","Prefer one-session-per-run when multi-run support is unverified"],"tags":["session","capability-missing","protocol"],"backgroundTag":"unsupported-operation","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}