agl 43.3.0 → 43.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/changelog.md +9 -0
  2. package/dist_serve/bundle.js +2 -2
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/classes.authstore.d.ts +7 -0
  6. package/dist_ts/classes.authstore.js +9 -1
  7. package/dist_ts/classes.claudeharness.d.ts +13 -2
  8. package/dist_ts/classes.claudeharness.js +12 -5
  9. package/dist_ts/classes.controller.d.ts +27 -6
  10. package/dist_ts/classes.controller.js +136 -39
  11. package/dist_ts/classes.mcpcontrollerhost.js +4 -1
  12. package/dist_ts/classes.mcptools.js +6 -1
  13. package/dist_ts/classes.nativesessions.d.ts +12 -0
  14. package/dist_ts/classes.nativesessions.js +1 -1
  15. package/dist_ts/classes.workercallers.js +4 -2
  16. package/dist_ts/driver/classes.directreports.js +19 -19
  17. package/dist_ts/driver/classes.directreportstore.d.ts +8 -1
  18. package/dist_ts/driver/classes.directreportstore.js +20 -10
  19. package/dist_ts/fleet/classes.workers.d.ts +16 -0
  20. package/dist_ts/fleet/classes.workers.js +73 -39
  21. package/dist_ts/fleet/classes.workerstore.js +14 -8
  22. package/dist_ts/fleet/functions.workervalidation.js +10 -3
  23. package/dist_ts/fleet/interfaces.workers.d.ts +6 -2
  24. package/dist_ts/fleet/interfaces.workers.js +8 -4
  25. package/dist_ts/functions.deviceapi.d.ts +50 -3
  26. package/dist_ts/functions.deviceapi.js +174 -7
  27. package/dist_ts/functions.exactpersistence.d.ts +3 -0
  28. package/dist_ts/functions.exactpersistence.js +4 -0
  29. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  30. package/dist_ts/functions.ticketactor.d.ts +17 -1
  31. package/dist_ts/functions.ticketactor.js +55 -15
  32. package/dist_ts_interfaces/devices.d.ts +17 -4
  33. package/dist_ts_interfaces/devices.js +1 -1
  34. package/dist_ts_interfaces/fleetworkers.d.ts +32 -7
  35. package/dist_ts_interfaces/fleetworkers.js +19 -8
  36. package/dist_ts_interfaces/workercallers.d.ts +2 -0
  37. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +14 -0
  38. package/dist_ts_migration/classes.documentmigrationrunner.js +20 -1
  39. package/dist_ts_migration/index.d.ts +1 -0
  40. package/dist_ts_migration/index.js +2 -1
  41. package/dist_ts_migration/v43_ticketactornames.d.ts +32 -0
  42. package/dist_ts_migration/v43_ticketactornames.js +236 -0
  43. package/package.json +1 -1
  44. package/readme.md +34 -3
  45. package/ts/00_commitinfo_data.ts +1 -1
  46. package/ts/classes.authstore.ts +10 -0
  47. package/ts/classes.claudeharness.ts +18 -4
  48. package/ts/classes.controller.ts +142 -40
  49. package/ts/classes.mcpcontrollerhost.ts +3 -0
  50. package/ts/classes.mcptools.ts +5 -0
  51. package/ts/classes.nativesessions.ts +13 -0
  52. package/ts/classes.workercallers.ts +3 -1
  53. package/ts/driver/classes.directreports.ts +18 -18
  54. package/ts/driver/classes.directreportstore.ts +20 -9
  55. package/ts/fleet/classes.workers.ts +66 -39
  56. package/ts/fleet/classes.workerstore.ts +11 -7
  57. package/ts/fleet/functions.workervalidation.ts +7 -2
  58. package/ts/fleet/interfaces.workers.ts +6 -2
  59. package/ts/functions.deviceapi.ts +227 -6
  60. package/ts/functions.exactpersistence.ts +5 -0
  61. package/ts/functions.mcpfleetworkertools.ts +1 -1
  62. package/ts/functions.ticketactor.ts +58 -14
  63. package/ts_interfaces/devices.schema.json +5 -2
  64. package/ts_interfaces/devices.ts +20 -4
  65. package/ts_interfaces/fleetworkers.ts +33 -7
  66. package/ts_interfaces/workercallers.ts +2 -0
  67. package/ts_migration/classes.documentmigrationrunner.ts +21 -0
  68. package/ts_migration/index.ts +1 -0
  69. package/ts_migration/v43_ticketactornames.ts +225 -0
  70. package/ts_web/00_commitinfo_data.ts +1 -1
  71. package/ts_web/elements.fleetworker.ts +4 -2
@@ -2,7 +2,8 @@ import { flexMessageDeliveryProof, type TFlexDeliveryEvidence, type TFlexDeliver
2
2
  import { FleetWorkers, fleetNativeSessionNames } from './fleet/classes.workers.js';
3
3
  import { FleetTicketEffects } from './fleet/classes.ticketeffects.js';
4
4
  import { FleetDispatchError, FleetWorkerError } from './fleet/interfaces.workers.js';
5
- import type { TFleetWorkerAction, TFleetWorkerRequest } from '../ts_interfaces/fleetworkers.js';
5
+ import { DirectReportError } from './driver/classes.directreportstore.js';
6
+ import type { IFleetWorkerJob, TFleetWorkerAction, TFleetWorkerRequest } from '../ts_interfaces/fleetworkers.js';
6
7
  import { ControllerBrowserOperationAuthority } from './classes.browseroperationauthority.js';
7
8
  import { ControllerWorkerCallers, type IWorkerCodexCallerOrigin } from './classes.workercallers.js';
8
9
  import { WorkerCallerBindingStore } from './classes.workercallerbindings.js';
@@ -118,6 +119,7 @@ import {
118
119
  assertDeviceDriverSendRequest,
119
120
  assertDeviceDirectReportMessageRequest,
120
121
  serveDeviceDriver,
122
+ deviceDirectReportJobRefusal,
121
123
  deviceDirectReportMessageRefusal,
122
124
  deviceHostAgl,
123
125
  deviceHostDevice,
@@ -134,6 +136,7 @@ import {
134
136
  deviceTicketDiscussion,
135
137
  deviceTicketPlans,
136
138
  deviceTicketRefusal,
139
+ deviceContractError,
137
140
  readDeviceTicketPlacement,
138
141
  type IDeviceTicketViewer,
139
142
  } from './functions.deviceapi.js';
@@ -601,12 +604,12 @@ import { SessionFeed, SessionFeedAcknowledgementError, SessionFeedTranscripts, s
601
604
  import { SessionFeedAcknowledgementStore } from './classes.sessionfeedacknowledgements.js';
602
605
  import { HarnessReleaseNotices, type THarnessReleaseSource } from './classes.harnessreleases.js';
603
606
  import { assertSessionFeedAcknowledgeRequest } from './functions.sessionfeedvalidation.js';
604
- import { NativeSessions, nativeSessionReadOnlyMessages, type IResolvedNativeSession } from './classes.nativesessions.js';
607
+ import { NativeSessions, nativeSessionReadOnlyMessages, type INativeSessionFailedErrorData, type IResolvedNativeSession } from './classes.nativesessions.js';
605
608
  import { claudeProfileForHome, fleetAdoptCommand, listUnboundDrivers } from './fleet/functions.unbounddrivers.js';
606
609
  import type { IReq_ControllerSessionFeedAcknowledge, IReq_ControllerSessionFeedList } from '../ts_interfaces/sessionfeed.js';
607
610
  import { UsageFeed, UsageFeedRefusal } from './classes.usagefeed.js';
608
611
  import type { IReq_ControllerUsageUnwatch, IReq_ControllerUsageWatch, TControllerUsageDelta } from '../ts_interfaces/metrics.js';
609
- import { ticketActorFromCaller } from './functions.ticketactor.js';
612
+ import { ticketActorFromCaller, ticketCallerSessionId } from './functions.ticketactor.js';
610
613
  import { ticketOwnerActor, ticketOwnerPrincipalId, resolveTicketOwnerAssignment } from './functions.ticketowner.js';
611
614
  import { assertTicketRequest, ticketInputSchemas } from './functions.ticketvalidation.js';
612
615
  import { readTicketRevisionConflict, type ITicket, type ITicketActor, type ITicketBoard, type ITicketComment, type ITicketDetail, type TTicketOperation, type TTicketRequest, type TTicketResponse, type TTicketFleetEvent, type ITicketFleetEventResult } from '../ts_interfaces/tickets.js';
@@ -3015,6 +3018,70 @@ const asTypedResponseError = (
3015
3018
  });
3016
3019
  };
3017
3020
 
3021
+ /**
3022
+ * The device error translation of both device scopes: a failure as `asTypedResponseError` reduces it, in the device
3023
+ * contract (`deviceContractError`), so no device method ever answers a code outside `TDeviceRefusalCode`.
3024
+ */
3025
+ const asDeviceResponseError = (
3026
+ errorArg: unknown,
3027
+ methodArg: string,
3028
+ ): plugins.typedrequest.TypedResponseError => deviceContractError(asTypedResponseError(errorArg, methodArg), errorArg, methodArg);
3029
+
3030
+ /**
3031
+ * A direct report operation's failure as the Driver view and a device receive it, decided by the error's class, never
3032
+ * its text: the refusals AGL writes itself keep their message as `direct_report_failed` (`DirectReportError`, the
3033
+ * direct reports' and their store's own, `FleetWorkerError` and `FleetNativeTurnError`, the fleet's), with a failure
3034
+ * journal reference where they stand for a dependency's error (`cause`); every other error, whose message may be a
3035
+ * dependency's (a spawn error, a socket path, a fleet job's recorded failure), is the controller's one generic failure,
3036
+ * `controller_operation_failed`, whose response carries the reference under which the failure journal keeps the cause
3037
+ * and which a device receives as its own (`deviceDirectReportMessageRefusal`, `deviceContractError`).
3038
+ */
3039
+ const directReportFailure = (errorArg: Error, operationArg: string): plugins.typedrequest.TypedResponseError => {
3040
+ if (errorArg instanceof DirectReportError || errorArg instanceof FleetWorkerError || errorArg instanceof FleetNativeTurnError) {
3041
+ const reference = errorArg.cause === undefined ? undefined : controllerFailureJournal.record({ operation: operationArg, cause: errorArg.cause });
3042
+ return new plugins.typedrequest.TypedResponseError(errorArg.message.slice(0, 4096), {
3043
+ code: 'direct_report_failed', ...(reference === undefined ? {} : { reference }),
3044
+ });
3045
+ }
3046
+ const reference = controllerFailureJournal.record({ operation: operationArg, cause: errorArg });
3047
+ console.error(`${currentRuntimeName} direct report operation failed (${operationArg}, ref ${reference}):`, errorArg);
3048
+ return new plugins.typedrequest.TypedResponseError('The controller operation failed.', { code: controllerOperationFailedErrorCode, reference });
3049
+ };
3050
+
3051
+ /**
3052
+ * A direct report message's settled fleet job as the Driver view receives it, by the same rule: a failure the fleet
3053
+ * refused itself (`errorCode`) keeps its text; any other job error, which may be a dependency's output (a harness's
3054
+ * own text, a failed delivery), reads "The controller operation failed." with the failure journal's reference, under
3055
+ * which the journal keeps it. The job's `errorOutcome` stays: the Driver view shows a failure that may have delivered
3056
+ * the message as of unknown outcome, never as a message the report did not take. A device's view of the job is
3057
+ * `deviceDirectReportJobRefusal`'s.
3058
+ */
3059
+ const directReportJobView = (jobArg: IFleetWorkerJob): IFleetWorkerJob => {
3060
+ if (jobArg.state !== 'failed' || jobArg.errorCode !== undefined) return jobArg;
3061
+ const cause = jobArg.error ?? 'The fleet job failed without an error.';
3062
+ const reference = controllerFailureJournal.record({ operation: 'directreport.message', cause });
3063
+ console.error(`${currentRuntimeName} direct report message failed in fleet job ${jobArg.id} (ref ${reference}):`, cause);
3064
+ return { ...jobArg, error: `The controller operation failed. (ref ${reference})` };
3065
+ };
3066
+
3067
+ /** The refusals of a native message's session, every one before its send: no such session, more than one, one it may not wake. */
3068
+ const fleetNativeMessageRefusals: ReadonlySet<string> = new Set(['session_not_found', 'ambiguous_session', 'session_read_only']);
3069
+
3070
+ /**
3071
+ * A failed fleet `native-message` in the fleet's terms, so its job's outcome says whether the message may have arrived
3072
+ * (`IFleetWorkerJob.errorOutcome`): a refusal that proves nothing reached the job, one of the send's own refusals of the
3073
+ * session (`fleetNativeMessageRefusals`, before the send and again under the session's lock) or a native send failure
3074
+ * that says `refused`, is a `FleetDispatchError` that sent nothing, with the same message; any other failure stays as
3075
+ * it is, an unknown outcome.
3076
+ */
3077
+ export const fleetNativeMessageFailure = (errorArg: unknown): unknown => {
3078
+ if (!(errorArg instanceof plugins.typedrequest.TypedResponseError)) return errorArg;
3079
+ const errorData = errorArg.errorData as Readonly<Record<string, unknown>> | undefined;
3080
+ const refused = typeof errorData?.code === 'string' && fleetNativeMessageRefusals.has(errorData.code)
3081
+ || errorData?.code === 'native_session_failed' && errorData.outcome === ('refused' satisfies INativeSessionFailedErrorData['outcome']);
3082
+ return refused ? new FleetDispatchError(errorArg.message, false, { cause: errorArg }) : errorArg;
3083
+ };
3084
+
3018
3085
  const hashResumeToken = (tokenArg: string): string =>
3019
3086
  plugins.crypto.createHash('sha256').update(tokenArg, 'utf8').digest('base64url');
3020
3087
 
@@ -3310,7 +3377,7 @@ export class OpenCodeController {
3310
3377
  this.fleetWorkerLaunches = new FleetWorkerLaunches({ hooks: () => this.workerCallerHooks, overlays: resolveAGLHomePaths().fleetMcpConfigs });
3311
3378
  }
3312
3379
  this.fleetWorkers = new FleetWorkers({ sample: () => this.systemMetricsSampler.sample(), ticketEffects: this.requireFleetTicketEffects(), sessionBindings: directReports,
3313
- nativeMessages: { send: (_owner, request, actor) => this.sendFleetNativeMessage(request, actor) },
3380
+ nativeMessages: { send: (_owner, request, actor) => this.sendFleetNativeMessage(request, actor).catch((errorArg: unknown) => { throw fleetNativeMessageFailure(errorArg); }) },
3314
3381
  claudeReleases: (releaseArg) => this.observeClaudeRelease(releaseArg, 'fleet'),
3315
3382
  // No controller event names a native thread; the Inbox reads the fleet connection's requests again.
3316
3383
  onNativeCodexAttention: () => this.inbox?.nativeAttentionChanged('codex'),
@@ -3342,9 +3409,14 @@ export class OpenCodeController {
3342
3409
  // The Driver view's owner relaunches unless a driver tool names its driver.
3343
3410
  const { job } = await fleetWorkers.execute('adopt', request, configuration, owner, signal, actor ?? ticketOwnerActor(await this.requireAuthStore().getState()));
3344
3411
  const settled = await fleetWorkers.settled(owner, job.id, signal);
3345
- if (settled.state !== 'succeeded') throw new Error(settled.error ?? 'The relaunch failed.');
3412
+ // A refusal the fleet wrote itself keeps its text; any other error may be a dependency's output, so it is the
3413
+ // cause the failure journal keeps (`directReportFailure`).
3414
+ if (settled.state !== 'succeeded') {
3415
+ if (settled.errorCode !== undefined) throw new FleetWorkerError(settled.errorCode, settled.error ?? 'The relaunch failed.');
3416
+ throw new Error(settled.error ?? 'The relaunch failed.');
3417
+ }
3346
3418
  const worker = (await fleetWorkers.views(owner)).find((view) => view.worker.name === request.name)?.worker;
3347
- if (!worker?.nativeId) throw new Error('The relaunched fleet worker is unavailable.');
3419
+ if (!worker?.nativeId) throw new DirectReportError('The relaunched fleet worker is unavailable.');
3348
3420
  return worker;
3349
3421
  },
3350
3422
  nativeSession: async (ref) => await this.nativeSessions.resolve(ref),
@@ -9590,7 +9662,7 @@ export class OpenCodeController {
9590
9662
  ): Promise<IControllerMcpNativeSessionDetail> {
9591
9663
  return this.runAudited(
9592
9664
  { type: 'session.read', peerId: this.auditPeerId(principalArg, 'mcp'), sessionId: requestArg.sessionId },
9593
- () => this.serveNativeSession(signalArg, async () => {
9665
+ () => this.serveNativeSession(signalArg, 'none', async () => {
9594
9666
  const { ref, resolved, session } = await this.requireMcpNativeClaudeTarget(requestArg.projectId, requestArg.sessionId);
9595
9667
  const [page, state] = await Promise.all([
9596
9668
  this.requireFleetWorkers().nativeHistory('claude', resolved.native, controllerInitialMessageBundleLimit),
@@ -9799,6 +9871,18 @@ export class OpenCodeController {
9799
9871
  return currentControllerMcpCaller();
9800
9872
  }
9801
9873
 
9874
+ /**
9875
+ * The owner's active direct report whose session an MCP caller acts in, read once per ticket request: a ticket names
9876
+ * the caller by it (AGL-1686). None for a caller without a session or whose session is no active report.
9877
+ */
9878
+ private async mcpCallerReportName(callerArg: IControllerMcpCaller): Promise<string | undefined> {
9879
+ const sessionId = ticketCallerSessionId(callerArg);
9880
+ if (sessionId === undefined) return undefined;
9881
+ const authority = this.configurationAuthority;
9882
+ if (!authority) throw new plugins.typedrequest.TypedResponseError('The configuration authority is unavailable.', { code: 'controller_unavailable' });
9883
+ return await this.requireDirectReports().reportOf((await authority.getResource()).resourceId, sessionId);
9884
+ }
9885
+
9802
9886
  private mcpIdentityRequired(): plugins.typedrequest.TypedResponseError {
9803
9887
  return new plugins.typedrequest.TypedResponseError(
9804
9888
  'This operation is available only to an AGL-launched chat; this MCP host has no AGL identity.',
@@ -10362,7 +10446,7 @@ export class OpenCodeController {
10362
10446
  // A worker a direct report's session starts, adopts, refreshes or moves reports to it.
10363
10447
  const caller = this.mcpCaller();
10364
10448
  const reportsTo = ['start', 'adopt', 'refresh', 'move'].includes(action) && caller.subject.kind !== 'anonymous'
10365
- ? await this.requireDirectReports().reportOf(owner.resourceId, ticketActorFromCaller(caller).sessionId) : undefined;
10449
+ ? await this.requireDirectReports().reportOf(owner.resourceId, ticketCallerSessionId(caller)) : undefined;
10366
10450
  try {
10367
10451
  return await this.requireFleetWorkers().execute(action, input as TFleetWorkerRequest<typeof action>, master.fleet ?? {}, owner.resourceId, operationSignal, actor, reportsTo);
10368
10452
  } catch (errorArg) {
@@ -10424,7 +10508,7 @@ export class OpenCodeController {
10424
10508
  resolveTicketOwnerAssignment(methodArg, request as TTicketRequest<typeof methodArg>, owner.id), actor, operationSignalArg);
10425
10509
  }
10426
10510
  const caller = this.mcpCaller();
10427
- const actor = caller.subject.kind === 'anonymous' ? undefined : ticketActorFromCaller(caller);
10511
+ const actor = caller.subject.kind === 'anonymous' ? undefined : ticketActorFromCaller(caller, await this.mcpCallerReportName(caller));
10428
10512
  return await this.ticketStore.execute(methodArg, request as TTicketRequest<typeof methodArg>, actor, operationSignalArg);
10429
10513
  } catch (errorArg) {
10430
10514
  if (errorArg instanceof TicketError) throw new plugins.typedrequest.TypedResponseError(errorArg.message,
@@ -10750,9 +10834,9 @@ export class OpenCodeController {
10750
10834
  : await resolveInitialRuntimeConfig(this.options.runtimeOverrides);
10751
10835
  this.assertStartActive();
10752
10836
  const authDocument = await authStore.resolveOrCreateRuntimeConfig(runtimeConfig);
10753
- await authStore.migrateTicketOwnerPrincipal();
10754
- const closed = await authStore.migrateTicketClosedColumn();
10837
+ const { closed, renamed } = await authStore.migrateTicketsAtStart();
10755
10838
  if (closed.length) console.log(`Moved ${closed.length} tickets released without a release link or any code link to closed (AGL-916): ${closed.join(', ')}.`);
10839
+ if (renamed.length) console.log(`Named the people of ${renamed.length} tickets by their role instead of their session id (AGL-1686): ${renamed.join(', ')}.`);
10756
10840
  this.assertStartActive();
10757
10841
  this.runtimeConfig = runtimeConfig;
10758
10842
  this.controllerId = authDocument.id;
@@ -14267,8 +14351,8 @@ export class OpenCodeController {
14267
14351
  const publicRouter = new plugins.typedrequest.TypedRouter();
14268
14352
  const browserAuthRouter = new plugins.typedrequest.TypedRouter();
14269
14353
  const protectedRouter = new ControllerProtectedRouter(asTypedResponseError);
14270
- const devicePairingRouter = new ControllerProtectedRouter(asTypedResponseError);
14271
- const deviceRouter = new ControllerProtectedRouter(asTypedResponseError);
14354
+ const devicePairingRouter = new ControllerProtectedRouter(asDeviceResponseError);
14355
+ const deviceRouter = new ControllerProtectedRouter(asDeviceResponseError);
14272
14356
  rootRouter.addTypedRouter(publicRouter);
14273
14357
  rootRouter.addTypedRouter(browserAuthRouter);
14274
14358
  rootRouter.addTypedRouter(protectedRouter);
@@ -14722,9 +14806,7 @@ export class OpenCodeController {
14722
14806
  throw deviceDirectReportMessageRefusal(errorArg);
14723
14807
  }
14724
14808
  if (!('job' in answer)) return { delivery: answer.delivery };
14725
- if (answer.job.state !== 'succeeded') {
14726
- throw deviceRefusal('direct_report_failed', (answer.job.error ?? 'The fleet did not deliver the message.').slice(0, 4096));
14727
- }
14809
+ if (answer.job.state !== 'succeeded') throw deviceDirectReportJobRefusal(answer.job);
14728
14810
  return { delivery: 'fleet' as const };
14729
14811
  }), toolsArg?.abortSignal);
14730
14812
  });
@@ -18946,7 +19028,7 @@ export class OpenCodeController {
18946
19028
  */
18947
19029
  private registerNativeSessionHandlers(protectedRouterArg: ControllerProtectedRouter): void {
18948
19030
  const runtimeId = nativeSessionRuntimeId;
18949
- const serve = <T>(signalArg: AbortSignal, operationArg: () => Promise<T>): Promise<T> => this.serveNativeSession(signalArg, operationArg);
19031
+ const serve = <T>(signalArg: AbortSignal, operationArg: () => Promise<T>): Promise<T> => this.serveNativeSession(signalArg, 'none', operationArg);
18950
19032
 
18951
19033
  protectedRouterArg.addHandler<IReq_ControllerNativeSessionRead>(
18952
19034
  'controller.nativesession.read',
@@ -18989,7 +19071,7 @@ export class OpenCodeController {
18989
19071
  await this.sendNativeSession(peer.id, ref, text, attachments, signalArg, assertNativeSessionWritable,
18990
19072
  { kind: 'agent', label: 'Owner', subject: agentMessageSubjects.ownerNativeView });
18991
19073
  // The session as the send left it, read apart from the audited send.
18992
- return { session: await this.serveNativeSession(signalArg, async () => (await this.nativeSessions.resolve(ref)).session) };
19074
+ return { session: await this.serveNativeSession(signalArg, 'none', async () => (await this.nativeSessions.resolve(ref)).session) };
18993
19075
  }, toolsArg?.abortSignal);
18994
19076
  },
18995
19077
  );
@@ -19126,7 +19208,7 @@ export class OpenCodeController {
19126
19208
  const sessionId = nativeSessionRuntimeId(ref);
19127
19209
  return this.runAudited(
19128
19210
  { type: 'session.read', peerId: this.auditPeerId(principalArg, peerIdArg), sessionId },
19129
- () => this.serveNativeSession(signalArg, async () => {
19211
+ () => this.serveNativeSession(signalArg, 'none', async () => {
19130
19212
  const resolved = await this.nativeSessions.resolve(ref);
19131
19213
  const [page, attention, state] = await Promise.all([
19132
19214
  this.requireFleetWorkers().nativeHistory(ref.harness, resolved.native, limit ?? controllerInitialMessageBundleLimit, before),
@@ -19169,7 +19251,7 @@ export class OpenCodeController {
19169
19251
  : ['question', { answers: requestArg.answers }];
19170
19252
  return this.runAudited(
19171
19253
  { type: `${kind}.reply`, peerId: this.auditPeerId(principalArg, peerIdArg), sessionId: nativeSessionRuntimeId(ref), requestId },
19172
- () => this.serveNativeSession(signalArg, async () => {
19254
+ () => this.serveNativeSession(signalArg, 'dispatch', async () => {
19173
19255
  const resolved = await this.nativeSessions.resolve(ref);
19174
19256
  await this.replyNativeSessionRequest(resolved, requestId.nativeId, reply, kind);
19175
19257
  return { success: true };
@@ -19215,17 +19297,25 @@ export class OpenCodeController {
19215
19297
  }
19216
19298
  }
19217
19299
 
19218
- /** Native session failures are bounded messages; the session view and the fleet's receipt show them as they are. */
19219
- private async serveNativeSession<T>(signalArg: AbortSignal, operationArg: () => Promise<T>): Promise<T> {
19300
+ /**
19301
+ * Native session failures are bounded messages; the session view and the fleet's receipt show them as they are. Each
19302
+ * says what it did (`INativeSessionFailedErrorData`). `effectArg` `none` means the operation sends the session
19303
+ * nothing (a read, the session's resolution, AGL's own scratchpad), so it is `refused`: a scratchpad save under `none`
19304
+ * is safe to repeat because its `expectedRevision` refuses a second write of the same revision. A send or an answer
19305
+ * (`dispatch`) is `refused` only where the fleet proved it never went out, and `unknown` otherwise.
19306
+ */
19307
+ private async serveNativeSession<T>(signalArg: AbortSignal, effectArg: 'none' | 'dispatch', operationArg: () => Promise<T>): Promise<T> {
19220
19308
  try {
19221
19309
  return await operationArg();
19222
19310
  } catch (errorArg) {
19223
19311
  if (signalArg.aborted || errorArg instanceof plugins.typedrequest.TypedResponseError || !(errorArg instanceof Error)) throw errorArg;
19224
19312
  // The session state store states its own refusals: a stale scratchpad revision, a missing record.
19225
19313
  if (errorArg instanceof AuthError) throw asTypedResponseError(errorArg, 'native session');
19226
- // Whether the message may have reached the session: a refusal before dispatch did not, a dispatched failure may have.
19227
- const outcome = errorArg instanceof FleetDispatchError ? { outcome: errorArg.dispatched ? 'unknown' as const : 'refused' as const } : {};
19228
- throw new plugins.typedrequest.TypedResponseError(errorArg.message.slice(0, 4096), { code: 'native_session_failed', ...outcome });
19314
+ const errorData: INativeSessionFailedErrorData = {
19315
+ code: 'native_session_failed',
19316
+ outcome: effectArg === 'none' || (errorArg instanceof FleetDispatchError && !errorArg.dispatched) ? 'refused' : 'unknown',
19317
+ };
19318
+ throw new plugins.typedrequest.TypedResponseError(errorArg.message.slice(0, 4096), errorData);
19229
19319
  }
19230
19320
  }
19231
19321
 
@@ -19250,7 +19340,7 @@ export class OpenCodeController {
19250
19340
  ownerArg?: IControllerPromptSender,
19251
19341
  ): Promise<{ job?: TControllerNativeJobDelivery }> {
19252
19342
  const sessionId = nativeSessionRuntimeId(refArg);
19253
- return this.runAudited({ type: 'session.send', peerId: peerIdArg, sessionId }, () => this.serveNativeSession(signalArg, async () => {
19343
+ return this.runAudited({ type: 'session.send', peerId: peerIdArg, sessionId }, () => this.serveNativeSession(signalArg, 'dispatch', async () => {
19254
19344
  const scope = (await this.nativeSessions.resolve(refArg)).scope;
19255
19345
  let job: TControllerNativeJobDelivery | undefined;
19256
19346
  await this.withSessionStateMutation(scope, sessionId, async () => {
@@ -19361,7 +19451,11 @@ export class OpenCodeController {
19361
19451
  } catch (errorArg) {
19362
19452
  if (errorArg instanceof ClaudeHarnessDispatchError && !errorArg.dispatched) {
19363
19453
  if (upload) cleanup();
19364
- throw new plugins.typedrequest.TypedResponseError(errorArg.message, { code: 'native_session_failed' });
19454
+ // Nothing went out: a busy conversation or host says so, which a sender reads as "try again once it ended".
19455
+ const errorData: INativeSessionFailedErrorData = {
19456
+ code: 'native_session_failed', outcome: 'refused', ...(errorArg.refusal === undefined ? {} : { refusal: errorArg.refusal }),
19457
+ };
19458
+ throw new plugins.typedrequest.TypedResponseError(errorArg.message, errorData);
19365
19459
  }
19366
19460
  // Claude Code may have taken the message: the turn settles as Claude Code reports it, and its upload goes with
19367
19461
  // it. A conversation that no longer holds the message lost its process, and with it the turn.
@@ -19422,15 +19516,15 @@ export class OpenCodeController {
19422
19516
  }
19423
19517
 
19424
19518
  /**
19425
- * A direct report operation for the owner's browser or a device, given the owner: its failures are bounded messages
19426
- * for the owner (`direct_report_failed`), which the Driver view and a device show as they are.
19519
+ * A direct report operation for the owner's browser or a device, given the owner: its failures reach them as
19520
+ * `directReportFailure` decides, by the error's class.
19427
19521
  */
19428
19522
  private async serveDirectReport<T>(signalArg: AbortSignal, operationArg: (ownerArg: string) => Promise<T>): Promise<T> {
19429
19523
  try {
19430
19524
  return await operationArg((await this.readFleetScope()).owner);
19431
19525
  } catch (errorArg) {
19432
19526
  if (signalArg.aborted || errorArg instanceof plugins.typedrequest.TypedResponseError || !(errorArg instanceof Error)) throw errorArg;
19433
- throw new plugins.typedrequest.TypedResponseError(errorArg.message.slice(0, 4096), { code: 'direct_report_failed' });
19527
+ throw directReportFailure(errorArg, 'directreport');
19434
19528
  }
19435
19529
  }
19436
19530
 
@@ -19504,9 +19598,10 @@ export class OpenCodeController {
19504
19598
  async (requestArg, toolsArg) => {
19505
19599
  const request = validateRequest(() => assertDirectReportMessageRequest(requestArg));
19506
19600
  const peer = peerFromLocalData(toolsArg?.localData);
19507
- return this.runOperation(peer, (signalArg) => serve(signalArg, async (ownerArg) => (
19508
- this.messageDirectReportForPrincipal('browser', peer.id, ownerArg, request, signalArg)
19509
- )), toolsArg?.abortSignal);
19601
+ return this.runOperation(peer, (signalArg) => serve(signalArg, async (ownerArg) => {
19602
+ const answer = await this.messageDirectReportForPrincipal('browser', peer.id, ownerArg, request, signalArg);
19603
+ return 'job' in answer ? { job: directReportJobView(answer.job) } : answer;
19604
+ }), toolsArg?.abortSignal);
19510
19605
  },
19511
19606
  );
19512
19607
  }
@@ -19514,9 +19609,11 @@ export class OpenCodeController {
19514
19609
  /**
19515
19610
  * The owner's own message to the active direct report `name`, from the Driver view or a paired device, audited as
19516
19611
  * `session.message` from the `Owner` for the caller. A fleet worker report is steered through the report's driver
19517
- * ticket, as the driver's `directreport_message` does, and answers with the settled steer job, audited `failed`
19518
- * unless the job succeeded; a steer the fleet refused is `direct_report_failed` with the fleet's reason, also audited
19519
- * `failed`. A Codex thread takes it as the owner's agent message.
19612
+ * ticket, as the driver's `directreport_message` does, and answers with the settled steer job as the fleet recorded
19613
+ * it, audited `failed` unless the job succeeded; the caller shows a failed job's error by its code
19614
+ * (`directReportJobView`, `deviceDirectReportJobRefusal`), and one that may have delivered it (`errorOutcome`) as of
19615
+ * unknown outcome. A steer the fleet refused is `direct_report_failed`
19616
+ * (`directReportFailure`), also audited `failed`. A Codex thread takes it as the owner's agent message.
19520
19617
  */
19521
19618
  private async messageDirectReportForPrincipal(
19522
19619
  principalArg: TControllerOperationPrincipal,
@@ -19537,7 +19634,10 @@ export class OpenCodeController {
19537
19634
  const { delivery, turnId } = await this.messageDirectReportSession(channel, 'owner', peerId, text, expectedTurnId);
19538
19635
  return { delivery, ...(turnId === undefined ? {} : { turnId }) };
19539
19636
  }
19540
- if (expectedTurnId !== undefined) throw new Error('expectedTurnId names the turn of a Codex thread; a fleet worker report is steered through its ticket.');
19637
+ if (expectedTurnId !== undefined) {
19638
+ throw new plugins.typedrequest.TypedResponseError('expectedTurnId names the turn of a Codex thread; a fleet worker report is steered through its ticket.',
19639
+ { code: 'invalid_request' });
19640
+ }
19541
19641
  return await this.runAudited({ type: 'session.message', peerId, sessionId: directReportRuntimeId(channel.report), senderLabel: 'Owner' }, async () => {
19542
19642
  try {
19543
19643
  const fleetWorkers = this.requireFleetWorkers();
@@ -19549,7 +19649,7 @@ export class OpenCodeController {
19549
19649
  } catch (errorArg) {
19550
19650
  // The fleet's own reason, as `serveDirectReport` gives it, before the audit would reduce it to a generic failure.
19551
19651
  if (signalArg.aborted || errorArg instanceof plugins.typedrequest.TypedResponseError || !(errorArg instanceof Error)) throw errorArg;
19552
- throw new plugins.typedrequest.TypedResponseError(errorArg.message.slice(0, 4096), { code: 'direct_report_failed' });
19652
+ throw directReportFailure(errorArg, 'directreport.message');
19553
19653
  }
19554
19654
  }, ({ job }) => job.state === 'succeeded' ? 'succeeded' : 'failed');
19555
19655
  }
@@ -20277,12 +20377,14 @@ export class OpenCodeController {
20277
20377
  try {
20278
20378
  result = await operationArg(operationId);
20279
20379
  } catch (error) {
20280
- // A refused workspace path is a policy decision, recorded as one; a direct report that took no message is a failure.
20380
+ // A refused workspace path is a policy decision, recorded as one; a direct report that took no message, and a fault
20381
+ // already reduced to the controller's generic failure, are failures.
20281
20382
  const outcome = (error instanceof AuthError
20282
20383
  || error instanceof plugins.typedrequest.TypedResponseError
20283
20384
  || error instanceof ControllerWorkspaceError
20284
20385
  || error instanceof ConfigurationError)
20285
- && !(error instanceof plugins.typedrequest.TypedResponseError && error.errorData?.code === 'direct_report_failed')
20386
+ && !(error instanceof plugins.typedrequest.TypedResponseError
20387
+ && (error.errorData?.code === 'direct_report_failed' || error.errorData?.code === controllerOperationFailedErrorCode))
20286
20388
  ? 'denied'
20287
20389
  : 'failed';
20288
20390
  const suppressUnboundedDenialAudit = error instanceof AuthError
@@ -316,6 +316,9 @@ const safeTypedResponseError = (
316
316
  project_not_found: 'The requested project is unavailable.',
317
317
  session_not_found: 'The requested session is unavailable.',
318
318
  session_read_only: 'The session takes no message now; session_read names why.',
319
+ // "Nothing was sent" holds because a `native_session_failed` reaching MCP says `outcome: 'refused'`: the MCP send
320
+ // path (`deliverNativeAgentMessage`) turns every other outcome into `outcome_unknown` first, and an operation
321
+ // that sends the session nothing is always `refused` (`serveNativeSession`).
319
322
  native_session_failed: 'The Claude Code session could not be reached, and nothing was sent; read the session before acting again.',
320
323
  ambiguous_session: 'The native ID exists on multiple connections; select its qualified AGL ID.',
321
324
  model_not_found: 'The selected model is unavailable.',
@@ -304,6 +304,11 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
304
304
  LIST_CURSOR_MISMATCH: 'The cursor pages another filter (archived, ticketKey, state, harness); repeat that filter or list again without cursor.',
305
305
  LIST_CURSOR_STALE: 'The cursor continues after a worker this owner no longer holds as it was; list again without cursor.',
306
306
  LIST_CURSOR_INVALID: 'The cursor is not the nextCursor of a fleet_worker_list summary page; list again without cursor.',
307
+ FLEET_UNAVAILABLE: 'The fleet admits no worker job now: it is closing, holds its most jobs, or cannot prove its own process. Try again later.',
308
+ WORKER_FENCED: 'The worker\'s dispatch fence stands in the way (an unresolved, running or lost dispatch, or a reconfirmation without its ticket comment). Read the worker with fleet_worker_get before acting again.',
309
+ WORKER_ARCHIVED: 'The worker is archived and takes no dispatch.',
310
+ TICKET_MISMATCH: 'The worker is bound to another ticket; name its ticket, or adopt its binding explicitly.',
311
+ WORKER_CONFLICT: 'The request does not fit what the fleet holds: the name is taken, the session is bound already, or the harness, profile or directory cannot serve it. Change the request.',
307
312
  REQUEST_FAILED: 'The private AGL controller request failed.',
308
313
  TURN_ENDED: 'The turn the message was to steer has ended; nothing was sent. Read the task before sending again.',
309
314
  AGENT_MESSAGES_DISABLED: 'The owner does not accept agent messages for this project.',
@@ -7,6 +7,7 @@ import type {
7
7
  TControllerNativeSessionReadOnlyReason,
8
8
  } from '../ts_interfaces/index.js';
9
9
  import type { IFleetNativeAgent, IFleetNativeSession, IFleetNativeThread } from './fleet/interfaces.workers.js';
10
+ import type { TClaudeDispatchRefusal } from './classes.claudeharness.js';
10
11
 
11
12
  /** Where the resolver finds native sessions: exactly the sources the session feed lists, never a path a caller names. */
12
13
  export interface INativeSessionSources {
@@ -27,6 +28,18 @@ export interface INativeSessionSources {
27
28
  directoryExists(path: string): Promise<boolean>;
28
29
  }
29
30
 
31
+ /**
32
+ * The data of a failed native session operation (`native_session_failed`), which says what it did: `refused`, nothing
33
+ * reached the session (an operation that sends it nothing, such as a read, or a send or answer refused before it went
34
+ * out, with `refusal` when a busy conversation or host refused it); `unknown`, the send or answer went out, or may have,
35
+ * and its effect is unknown.
36
+ */
37
+ export interface INativeSessionFailedErrorData {
38
+ code: 'native_session_failed';
39
+ outcome: 'refused' | 'unknown';
40
+ refusal?: TClaudeDispatchRefusal;
41
+ }
42
+
30
43
  /** A native session as the resolver found it in one of its sources. */
31
44
  export interface IResolvedNativeSession {
32
45
  session: IControllerNativeSession;
@@ -629,7 +629,9 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
629
629
  controllerGeneration: this.options.controllerGeneration, bindingRevision: revision,
630
630
  projectId: recordArg.launch.projectId, harnessId: recordArg.launch.harnessId,
631
631
  nativeSessionId: recordArg.binding.nativeSessionId, ticketSessionId: recordArg.ticketSessionId!,
632
- sessionIdentityId: plugins.crypto.createHash('sha256').update(recordArg.ticketSessionId!).digest('base64url') });
632
+ sessionIdentityId: plugins.crypto.createHash('sha256').update(recordArg.ticketSessionId!).digest('base64url'),
633
+ // A worker id is `${projectId}:${name}`: prepared and kept launches are refused otherwise.
634
+ workerName: recordArg.launch.workerId.slice(recordArg.launch.projectId.length + 1) });
633
635
  recordArg.credentials.set(bridgePidArg, { credential, bridge, bindingRevision: revision });
634
636
  return { ...this.getWorkerCallerStatus(recordArg.launch.launchId), credential };
635
637
  });
@@ -7,7 +7,7 @@ import * as plugins from '../plugins.js';
7
7
  import type { IFleetSessionBindingFailure, IFleetSessionBindings } from '../fleet/classes.workers.js';
8
8
  import type { IFleetNativeAgent, IFleetNativeThread } from '../fleet/interfaces.workers.js';
9
9
  import type { IResolvedNativeSession } from '../classes.nativesessions.js';
10
- import { DirectReportConflictError, DirectReportStore, type IDirectReportStore } from './classes.directreportstore.js';
10
+ import { DirectReportConflictError, DirectReportError, DirectReportStore, type IDirectReportStore } from './classes.directreportstore.js';
11
11
 
12
12
  /** What direct reports read from the fleet, the native inventories and the ticket board; the controller supplies it. */
13
13
  export interface IDirectReportsHost {
@@ -54,7 +54,7 @@ export const directReportReachable = (report: IDirectReport): boolean => report.
54
54
  /** The native session a report is (`IDirectReport.sessionId`, `harness:nativeId`) as a runtime id. */
55
55
  export const directReportRuntimeId = (report: IDirectReport): { harnessId: TFleetWorkerHarness; nativeId: string } => {
56
56
  const separator = report.sessionId.indexOf(':'), harnessId = report.sessionId.slice(0, separator), nativeId = report.sessionId.slice(separator + 1);
57
- if (separator < 0 || (harnessId !== 'claude' && harnessId !== 'codex') || !nativeId) throw new Error(`Direct report ${report.name} names no Claude Code or Codex session.`);
57
+ if (separator < 0 || (harnessId !== 'claude' && harnessId !== 'codex') || !nativeId) throw new DirectReportError(`Direct report ${report.name} names no Claude Code or Codex session.`);
58
58
  return { harnessId, nativeId };
59
59
  };
60
60
 
@@ -153,9 +153,9 @@ export class DirectReports implements IFleetSessionBindings {
153
153
  /** Appoints the fleet worker `workerName`, bound to a native session and a ticket, as the report `name`. */
154
154
  public async appoint(owner: string, request: IReq_ControllerDirectReportAppoint['request'], signal?: AbortSignal): Promise<IDirectReportView> {
155
155
  const workers = await this.host.workers(owner), worker = workers.find((view) => view.worker.name === request.workerName)?.worker;
156
- if (!worker) throw new Error('The fleet worker is unavailable.');
157
- if (!worker.nativeId) throw new Error('The fleet worker has no native session yet.');
158
- if (!worker.ticketKey) throw new Error('The fleet worker is bound to no ticket; a direct report is steered through its ticket.');
156
+ if (!worker) throw new DirectReportError('The fleet worker is unavailable.');
157
+ if (!worker.nativeId) throw new DirectReportError('The fleet worker has no native session yet.');
158
+ if (!worker.ticketKey) throw new DirectReportError('The fleet worker is bound to no ticket; a direct report is steered through its ticket.');
159
159
  const projects = request.projects ?? [await this.host.ticketProject(worker.ticketKey, signal)];
160
160
  const report = await this.store.create(owner, this.report(owner, request.name, { kind: 'fleet-worker', workerName: worker.name },
161
161
  `${worker.harness}:${worker.nativeId}`, projects, worker.ticketKey));
@@ -208,15 +208,15 @@ export class DirectReports implements IFleetSessionBindings {
208
208
  public async adopt(owner: string, request: IReq_ControllerDirectReportAdopt['request'], signal?: AbortSignal, actor?: ITicketActor): Promise<IDirectReportView> {
209
209
  const { harness, nativeId, relaunch } = request;
210
210
  if (harness === 'claude' && !relaunch) {
211
- throw new Error('A Claude Code session is adopted with a relaunch: the fleet resumes it under its own control, which gives it a verified identity.');
211
+ throw new DirectReportError('A Claude Code session is adopted with a relaunch: the fleet resumes it under its own control, which gives it a verified identity.');
212
212
  }
213
- if (harness === 'codex' && relaunch) throw new Error('A Codex thread is adopted by reference; only a Claude Code session is relaunched.');
213
+ if (harness === 'codex' && relaunch) throw new DirectReportError('A Codex thread is adopted by reference; only a Claude Code session is relaunched.');
214
214
  if ((await this.host.workers(owner)).some((view) => view.worker.harness === harness && view.worker.nativeId === nativeId)) {
215
- throw new Error('A fleet worker is bound to this session; appoint the worker instead.');
215
+ throw new DirectReportError('A fleet worker is bound to this session; appoint the worker instead.');
216
216
  }
217
217
  const observations: IDirectReportObservations = harness === 'claude' ? { claude: await this.host.claudeSessions() } : { codex: await this.host.codexThreads() };
218
218
  const session = (observations.claude ?? observations.codex ?? []).find((item) => item.sessionId === nativeId);
219
- if (!session) throw new Error(`The ${harness === 'claude' ? 'Claude Code session' : 'Codex thread'} is not on this host.`);
219
+ if (!session) throw new DirectReportError(`The ${harness === 'claude' ? 'Claude Code session' : 'Codex thread'} is not on this host.`);
220
220
  const project = await this.host.ticketProject(request.driverTicketKey, signal);
221
221
  if (!relaunch) {
222
222
  const report = await this.store.create(owner, this.report(owner, request.name, { kind: 'session', harness, nativeId },
@@ -225,14 +225,14 @@ export class DirectReports implements IFleetSessionBindings {
225
225
  }
226
226
  // Refused before the relaunch: a session that ran as a report keeps that report, and a name stays taken once used.
227
227
  const reports = await this.store.list(owner);
228
- if (reports.some((report) => report.name === request.name)) throw new Error('A direct report of that name exists.');
229
- if (reports.some((report) => report.state === 'active' && report.sessionId === `claude:${nativeId}`)) throw new Error('Another active direct report already holds this session.');
228
+ if (reports.some((report) => report.name === request.name)) throw new DirectReportError('A direct report of that name exists.');
229
+ if (reports.some((report) => report.state === 'active' && report.sessionId === `claude:${nativeId}`)) throw new DirectReportError('Another active direct report already holds this session.');
230
230
  // Only the host's own Claude Code home holds project conversations; a session its profile's home does not list is
231
231
  // refused by the relaunch itself.
232
232
  if ((await this.host.claudeProfiles()).some((profile) => profile.id === relaunch.profile && profile.home === undefined)) {
233
233
  const listed = await this.host.nativeSession({ harness: 'claude', nativeId }).catch((error: unknown) => { if (notListed(error)) return undefined; throw error; });
234
234
  if (listed?.session.readOnly?.reason === 'projectConversation') {
235
- throw new Error('An AGL project conversation records this Claude Code session, so it stays that project\'s: a relaunch would give the conversation a second writer.');
235
+ throw new DirectReportError('An AGL project conversation records this Claude Code session, so it stays that project\'s: a relaunch would give the conversation a second writer.');
236
236
  }
237
237
  }
238
238
  const worker = await this.host.relaunch(owner, { name: relaunch.workerName ?? request.name, profile: relaunch.profile, cwd: relaunch.cwd ?? session.cwd,
@@ -242,7 +242,7 @@ export class DirectReports implements IFleetSessionBindings {
242
242
  report = await this.store.create(owner, this.report(owner, request.name, { kind: 'fleet-worker', workerName: worker.name },
243
243
  `${worker.harness}:${worker.nativeId}`, request.projects ?? [project], request.driverTicketKey));
244
244
  } catch (error) {
245
- throw new Error(`The session was relaunched as fleet worker ${worker.name}, but its direct report was not recorded: ${error instanceof Error ? error.message : String(error)} Appoint the worker as the report.`.slice(0, 4096));
245
+ throw new DirectReportError(`The session was relaunched as fleet worker ${worker.name}, but its direct report was not recorded. Appoint the worker as the report.`, { cause: error });
246
246
  }
247
247
  return this.view(report, { workers: await this.host.workers(owner) }, await this.host.openQuestions(signal));
248
248
  }
@@ -250,7 +250,7 @@ export class DirectReports implements IFleetSessionBindings {
250
250
  /** Retires the report; its session is left as it is. */
251
251
  public async retire(owner: string, name: string): Promise<IDirectReport> {
252
252
  return await this.serialized(owner, name, () => this.store.update(owner, name, (report) => {
253
- if (report.state === 'retired') throw new Error('The direct report is retired.');
253
+ if (report.state === 'retired') throw new DirectReportError('The direct report is retired.');
254
254
  report.state = 'retired';
255
255
  }));
256
256
  }
@@ -264,14 +264,14 @@ export class DirectReports implements IFleetSessionBindings {
264
264
  */
265
265
  public async channelOf(owner: string, name: string): Promise<TDirectReportChannel> {
266
266
  const report = await this.store.get(owner, name);
267
- if (!report || report.state !== 'active') throw new Error(`Direct report ${name} is not an active direct report.`);
267
+ if (!report || report.state !== 'active') throw new DirectReportError(`Direct report ${name} is not an active direct report.`);
268
268
  const session = report.session;
269
269
  if (session.kind === 'fleet-worker') return { kind: 'fleet-worker', report, workerName: session.workerName };
270
270
  if (!directReportReachable(report)) {
271
- throw new Error(`Direct report ${name} is a Claude Code session the fleet does not run, so it cannot be read or messaged: AGL reaches a Claude Code session only by resuming it in a process of its own, a second writer beside the one that runs it. Adopt the session with a relaunch (directreport_adopt) once it has settled.`);
271
+ throw new DirectReportError(`Direct report ${name} is a Claude Code session the fleet does not run, so it cannot be read or messaged: AGL reaches a Claude Code session only by resuming it in a process of its own, a second writer beside the one that runs it. Adopt the session with a relaunch (directreport_adopt) once it has settled.`);
272
272
  }
273
273
  const thread = (await this.host.codexThreads()).find((item) => item.sessionId === session.nativeId);
274
- if (!thread) throw new Error(`Direct report ${name}'s Codex thread ${session.nativeId} is not among the threads of this host's Codex server.`);
274
+ if (!thread) throw new DirectReportError(`Direct report ${name}'s Codex thread ${session.nativeId} is not among the threads of this host's Codex server.`);
275
275
  return { kind: 'session', report, nativeId: session.nativeId, cwd: thread.cwd };
276
276
  }
277
277
 
@@ -345,7 +345,7 @@ export class DirectReports implements IFleetSessionBindings {
345
345
  const current = await this.store.get(owner, name), move = current && directReportMove(current, workers);
346
346
  if (!current || !move) return;
347
347
  const ticketKey = move.to.ticketKey;
348
- if (current.session.kind === 'session' && !ticketKey) throw new Error(`Fleet worker ${move.to.name} is bound to no ticket.`);
348
+ if (current.session.kind === 'session' && !ticketKey) throw new DirectReportError(`Fleet worker ${move.to.name} is bound to no ticket.`);
349
349
  try {
350
350
  await this.store.update(owner, name, (next) => {
351
351
  if (!plugins.util.isDeepStrictEqual(next, current)) throw new DirectReportConflictError();