@parall/agent-core 1.43.0 → 1.45.0

package/src/gateway-lane-flow.ts

@@ -1,3 +1,4 @@
+import { ApiError } from '@parall/sdk';
 import type { ParallClient } from '@parall/sdk';
 import type { DispatchAdapter, GatewayLogger } from './dispatch-adapter.js';
 import type { DispatchableMessage, MessageDispatchDecision } from './gateway-base.js';
@@ -16,8 +17,15 @@ import type { ParallEvent } from './types.js';
 export interface LaneFlowHost {
   laneLedger?: LaneLedger;
   ledgerDisabled: boolean;
+  /**
+   * Sticky: the server answered a by-id complete with 400 (predates the
+   * form, v1.44). Typed resolution falls back to the legacy ack for the
+   * rest of the process; claims stay on the ledger (that face is older).
+   */
+  typedByIdCompleteUnsupported: boolean;
   shuttingDown: boolean;
   dispatchedMessages: Set<string>;
+  dispatchedTasks: Set<string>;
   /**
    * Per-WorkItem failure backoff for typed dispatch consumption. A consume
    * that ends without an ack re-arms the entry; the next attempt for the
@@ -37,6 +45,8 @@ export interface LaneFlowHost {
   disableLedger(reason: string): void;
   usesLaneLedger(event: ParallEvent): boolean;
   emitDispatchReceived(event: ParallEvent): Promise<void>;
+  consumeTurnError(sessionKey: string): boolean;
+  noteSessionLane(sessionKey: string, laneKey: string | null): void;
   runDispatch(
     event: ParallEvent,
     sessionKey: string,
@@ -68,7 +78,7 @@ export async function dispatchLaneGroup(
     captureText?: string[];
     hasMoreLocal: () => boolean;
   },
-): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
   const ledger = host.laneLedger!;
   const event = opts.events[opts.events.length - 1];
   let lane: Awaited<ReturnType<LaneLedger['ensureLane']>>;
@@ -106,6 +116,9 @@ export async function dispatchLaneGroup(
     }
     return 'foreign';
   }
+  // Register the session's active lane so external activity signals
+  // (touchRuntimeActivity from adapter hooks) renew exactly this lane.
+  host.noteSessionLane(opts.sessionKey, lane.laneKey);
   let dispatched = false;
   try {
     dispatched = await host.runDispatch(
@@ -118,32 +131,253 @@ export async function dispatchLaneGroup(
   } catch (err) {
     // Failed turn: hand the members back so the retry (this pod or the
     // next) re-claims immediately instead of waiting out the lease.
+    host.noteSessionLane(opts.sessionKey, null);
     await ledger.release(lane.laneKey).catch(() => {});
     throw err;
+  } finally {
+    if (dispatched) host.noteSessionLane(opts.sessionKey, null);
   }
   if (!dispatched) {
     // Shutdown short-circuit — shutdown() releases all active lanes.
     return 'shutdown';
   }
+  if (host.consumeTurnError(opts.sessionKey)) {
+    // An error turn must not no_action-sweep its members — settle the lane
+    // NOW with an error complete so they release for retry on the redrive
+    // budget (dispatch-convergence-design.md §3). Settling immediately (even
+    // with same-lane work still buffered) is deliberate: carrying the error
+    // across buffered turns would let a later reply broad-cover the failed
+    // member, or requeue the later turn's successful work. Released members
+    // rejoin the next claim, merged with whatever was buffered. Dropping the
+    // local dedupe claims lets the server's re-drive hint retrigger the
+    // messages immediately instead of waiting out the renotify pacing.
+    ledger.markTurnError(lane.laneKey);
+    // Clear dedupe for EVERY lane member, not just this batch: an earlier
+    // successful batch may have deferred its complete via hasMoreLocal, so
+    // the error complete below releases those members too — their redrive
+    // would be permanently blocked by a stale local claim.
+    for (const msgId of lane.folded.keys()) {
+      host.dispatchedMessages.delete(msgId);
+    }
+    // Invalidate any armed steer state before settling: a pending injection
+    // left over from the failed turn would make the retry claim enter the
+    // "already injected" path, produce an empty turn, and no_action-sweep the
+    // released members without ever retrying them. abortDispatch is the
+    // adapter contract's idempotent "clear pending steer state" hook.
+    try {
+      host.opts.dispatchAdapter.abortDispatch?.(opts.sessionKey);
+    } catch {
+      // best-effort — a throwing abort must not block the error settlement
+    }
+    await ledger.completeIfIdle(lane.laneKey, false);
+    // 'failed' — callers must NOT record these events as handled: the server
+    // just released them for redelivery, and an "already handled" fork prefix
+    // (or a consumed fork summary) on the redrive would be a lie.
+    return 'failed';
+  }
   const pendingInjections =
     host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
   await ledger.completeIfIdle(lane.laneKey, pendingInjections || opts.hasMoreLocal());
   return 'dispatched';
 }
 
+/**
+ * The WorkItem ids of a typed event group whose lifecycle the ledger owns
+ * (claimed into dsp lanes by consumeTypedDispatch), or null when the group
+ * must stay on the legacy received/ack surface — ledger unavailable, an id
+ * missing, or a member that rides a message lane. Non-null means: skip
+ * legacy received+ack, resolve via the by-id complete, and fold the
+ * turn-error signal into the outcome.
+ */
+export function typedLedgerEventIds(host: LaneFlowHost, events: ParallEvent[]): string[] | null {
+  if (!host.laneLedger || host.ledgerDisabled) return null;
+  const ids: string[] = [];
+  for (const ev of events) {
+    if (!ev.dispatchEventId || host.usesLaneLedger(ev)) return null;
+    ids.push(ev.dispatchEventId);
+  }
+  return ids.length > 0 ? ids : null;
+}
+
+/** Outcome of a by-id complete attempt. */
+export type TypedResolveOutcome = 'ok' | 'stale' | 'unsupported' | 'failed';
+
+/**
+ * A pre-by-id server (v1.44) routes a by-id body into its lane-form
+ * validation and answers 400 INVALID_REQUEST. Any 400 here means the server
+ * did not understand the form — a well-formed by-id call never 400s on a
+ * current server — so the caller falls back to the legacy typed ack for the
+ * rest of the process (sticky; the bridge restarts on the next update).
+ */
+function isByIDCompleteUnsupported(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 400;
+}
+
+/**
+ * By-id complete (turn_outcome ok): terminal resolution of ONE WorkItem —
+ * exact where the source pair is ambiguous across task siblings. `lane`
+ * fences the call while the row is claim-owned (a dethroned caller gets
+ * 'stale' and must leave the row to its successor); omit it for the
+ * wrapper-less pending close (buffered drain, administrative drops).
+ */
+export async function resolveDispatchByID(
+  host: LaneFlowHost,
+  dispatchEventId: string,
+  lane?: string,
+): Promise<TypedResolveOutcome> {
+  try {
+    await host.opts.client.completeDispatch(host.opts.config.org_id, {
+      dispatch_event_id: dispatchEventId,
+      ...(lane ? { lane } : {}),
+      turn_outcome: 'ok',
+    });
+    return 'ok';
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409) return 'stale';
+    if (isByIDCompleteUnsupported(err)) return 'unsupported';
+    host.opts.log?.warn(
+      `by-id complete failed for ${dispatchEventId} — leaving for re-drive: ${String(err)}`,
+    );
+    return 'failed';
+  }
+}
+
+/**
+ * Free a typed event's in-memory hot-path dedupe claim by its source pair —
+ * the ParallEvent-keyed mirror of the gateway's clearTypedDispatchDedupe
+ * (which keys on the wire DispatchNewData). Used when a buffered typed
+ * dispatch ran but its resolution failed: the member re-drives, and a stale
+ * local claim would make this pod reject the retry forever.
+ *
+ * PARITY: the switch below and clearTypedDispatchDedupe's must handle the
+ * same typed source families — when adding a new typed event type, extend
+ * BOTH (they key the same dedupe entries from different event shapes).
+ */
+export function clearTypedDedupeForEvent(host: LaneFlowHost, event: ParallEvent): void {
+  const sourceId = event.ackSourceId;
+  if (!sourceId) return;
+  switch (event.ackSourceType) {
+    case 'task_activity': {
+      // Task dedupe keys are `${task_id}:${updated_at}`; the task id is the
+      // event target. Prefix-clear mirrors clearTypedDispatchDedupe.
+      const prefix = `${event.targetId}:`;
+      for (const key of host.dispatchedTasks) {
+        if (key.startsWith(prefix)) host.dispatchedTasks.delete(key);
+      }
+      break;
+    }
+    case 'comment':
+      host.dispatchedTasks.delete(`comment:${sourceId}`);
+      break;
+    case 'schedule_run':
+      host.dispatchedTasks.delete(`schedule_run:${sourceId}`);
+      break;
+    case 'external_trigger_run':
+      host.dispatchedTasks.delete(`external_trigger_run:${sourceId}`);
+      break;
+    case 'channel_message':
+      host.dispatchedMessages.delete(`channel_message:${sourceId}`);
+      break;
+    case 'approval':
+      host.dispatchedTasks.delete(`approval:${sourceId}`);
+      break;
+  }
+}
+
+/**
+ * Settle a drained typed group — the one wrapper-less dispatch path: these
+ * events buffered behind a busy main (fork-less adapter), their consume
+ * guards returned false and released the claims, so the drain site owns the
+ * terminal resolution. Rows are pending — the by-id close resolves them
+ * without a fence; a row a successor lane meanwhile claimed answers stale and
+ * is that owner's to finish. `turnErrored` (consumed at the call site before
+ * the drain can start another turn) leaves the rows for the renotify pacing
+ * instead. Either way a row left live gets its local dedupe claim freed, or
+ * this pod would reject the retry forever.
+ */
+export async function settleDrainedTypedGroup(
+  host: LaneFlowHost,
+  events: ParallEvent[],
+  ids: string[],
+  turnErrored: boolean,
+): Promise<void> {
+  if (turnErrored) {
+    host.opts.log?.info(
+      `buffered typed turn for ${events[events.length - 1]?.messageId} surfaced a runtime error — leaving for re-drive`,
+    );
+    for (const event of events) clearTypedDedupeForEvent(host, event);
+    return;
+  }
+  // The legacy ack BY ID, never by source — task siblings share a source
+  // pair, and a by-source ack would sweep the undispatched one. Awaited:
+  // these rows are already pending (released at buffer time), so a failed
+  // ack must free the local dedupe claim or the pending retry would be
+  // self-rejected by this pod forever.
+  const legacyAckFrom = async (start: number) => {
+    for (const [j, id] of ids.slice(start).entries()) {
+      try {
+        await host.opts.client.ackDispatchByID(host.opts.config.org_id, id);
+      } catch {
+        clearTypedDedupeForEvent(host, events[start + j]);
+      }
+    }
+  };
+  if (host.typedByIdCompleteUnsupported) {
+    // Sticky: the server already answered one by-id probe with 400 — go
+    // straight to the legacy acks instead of re-probing per group.
+    await legacyAckFrom(0);
+    return;
+  }
+  for (const [i, id] of ids.entries()) {
+    const outcome = await resolveDispatchByID(host, id);
+    if (outcome === 'unsupported') {
+      host.typedByIdCompleteUnsupported = true;
+      host.opts.log?.warn(
+        'server predates the by-id dispatch complete — falling back to legacy typed acks',
+      );
+      await legacyAckFrom(i);
+      return;
+    }
+    if (outcome !== 'ok') {
+      clearTypedDedupeForEvent(host, events[i]);
+    }
+  }
+}
+
 /** Failure backoff pacing for typed dispatch retries (base 2s, cap 5min). */
 const TYPED_BACKOFF_BASE_MS = 2_000;
 const TYPED_BACKOFF_CAP_MS = 5 * 60_000;
 const TYPED_BACKOFF_MAP_CAP = 512;
 
+/** Consumption hooks for one typed dispatch. */
+export interface TypedConsumeHooks {
+  /**
+   * Legacy administrative ack — invoked ONLY on the ledger-disabled fallback
+   * path (old server). On the ledger path the WorkItem resolves through the
+   * sources-form complete instead; this callback never fires there.
+   */
+  legacyAck: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>;
+  /**
+   * Free the item's in-memory hot-path dedupe claim. Invoked when the handler
+   * ran but the resolution could not commit (sources-form complete failed) —
+   * the member is released for re-drive, and a stale local claim would make
+   * this pod reject its own retry forever.
+   */
+  clearDedupe?: () => void;
+}
+
 /**
  * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
  * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
- * pod holds it or the WorkItem is already resolved), run the handler, ack on
- * success (the doc's option (b): notification delivered, tracked elsewhere),
- * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ * pod holds it or the WorkItem is already resolved), run the handler, then
+ * settle. A successful run resolves the WorkItem terminally via the
+ * sources-form complete (turn_outcome ok — the server sweeps it, or lets a
+ * typed Effect committed during the turn stand, and drops the vacated lane);
+ * a failed / errored / unresolved run releases the member back to pending on
+ * the redrive budget via the lane complete. Legacy run+ack flow when the
+ * ledger is unavailable.
  *
- * Repeated failures back off: a consume that ends un-acked re-arms the
+ * Repeated failures back off: a consume that ends unresolved re-arms the
  * WorkItem's backoff entry, and the next attempt sleeps out the remaining
  * window before claiming. Without this, complete's release re-drives the
  * item instantly and a persistently-failing consume (e.g. buffered behind a
@@ -154,7 +388,7 @@ export async function consumeTypedDispatch(
   host: LaneFlowHost,
   ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
   run: (dispatchEventId?: string) => Promise<boolean>,
-  ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
+  hooks: TypedConsumeHooks,
 ): Promise<void> {
   const backoffKey = ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`;
   const armed = host.typedRedriveBackoff.get(backoffKey);
@@ -179,8 +413,8 @@ export async function consumeTypedDispatch(
   // consume — clearing backoff there would let an ack outage re-create the
   // wire-speed release/re-drive loop against a pre-budget server.
   const settleAck = (ackResult: boolean | void) => ackResult !== false;
-  const settle = (acked: boolean) => {
-    if (acked) {
+  const settle = (resolved: boolean) => {
+    if (resolved) {
       host.typedRedriveBackoff.delete(backoffKey);
       return;
     }
@@ -207,7 +441,7 @@ export async function consumeTypedDispatch(
     let acked = false;
     try {
       if (await run(ref.dispatchEventId)) {
-        acked = settleAck(await ack(ref.dispatchEventId));
+        acked = settleAck(await hooks.legacyAck(ref.dispatchEventId));
       }
     } finally {
       settle(acked);
@@ -237,20 +471,65 @@ export async function consumeTypedDispatch(
     );
     return;
   }
-  let acked = false;
+  let resolved = false;
+  let viaLegacyAck = false;
   try {
-    // Ack must settle before Complete. A fire-and-forget ack races the lane
-    // release: Complete can return the still-received typed item to pending
-    // and publish a re-drive while its successful ack is still in flight.
+    // A successful run resolves the member terminally through the by-id
+    // complete — one fenced call that sweeps exactly this WorkItem (a typed
+    // Effect committed during the turn already made it terminal — idempotent
+    // no-op) AND drops the vacated lane. Resolution must settle inside this
+    // guard: a fire-and-forget resolve would race the finally's release and
+    // spuriously re-drive handled work.
     if (await run(lane.typedDispatchEventId)) {
-      acked = settleAck(await ack(lane.typedDispatchEventId));
+      if (host.typedByIdCompleteUnsupported || !lane.typedDispatchEventId) {
+        // Pre-by-id server (or a defensive claim shape without the id):
+        // the legacy administrative ack is still live there.
+        viaLegacyAck = true;
+        resolved = settleAck(await hooks.legacyAck(lane.typedDispatchEventId));
+      } else {
+        const outcome = await resolveDispatchByID(host, lane.typedDispatchEventId, lane.lane);
+        if (outcome === 'unsupported') {
+          host.typedByIdCompleteUnsupported = true;
+          host.opts.log?.warn(
+            'server predates the by-id dispatch complete — falling back to the legacy typed ack',
+          );
+          viaLegacyAck = true;
+          resolved = settleAck(await hooks.legacyAck(lane.typedDispatchEventId));
+        } else if (outcome === 'stale') {
+          // A successor lane owns the row — its turn resolves it. Nothing to
+          // spin on locally; our claim record is already dethroned. Free the
+          // local dedupe claim though: if the successor later FAILS and
+          // releases the row, the re-drive may land back on this pod, and a
+          // stale local claim would self-reject the retry into the budget.
+          hooks.clearDedupe?.();
+          resolved = true;
+        } else {
+          resolved = outcome === 'ok';
+          if (!resolved) {
+            // The member is about to be released for re-drive — free its
+            // hot-path dedupe claim first, or this pod rejects its own retry
+            // forever (same contract as the legacy ack-failure path).
+            hooks.clearDedupe?.();
+          }
+        }
+      }
     }
   } finally {
-    settle(acked);
-    // Release the occupancy row. A buffered dispatch may outlive this guard
-    // (lane TTL) — acceptable at-least-once; the ledger's resolution paths
-    // still dedupe the persistent side effects.
-    await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => {});
+    settle(resolved);
+    if (resolved && !viaLegacyAck) {
+      // The by-id complete already dropped (or a takeover already owns) the
+      // server-side lane row; only the local record and context file remain.
+      host.laneLedger.dropLocal(lane.laneKey);
+    } else {
+      // Two jobs, one call: an unresolved turn (unconsumed / failed /
+      // errored / resolution-failed) releases the member back to pending on
+      // the redrive budget; a legacy-acked turn still needs its server-side
+      // lane row dropped (the ack resolves the row but not the occupancy).
+      // A buffered dispatch may outlive this guard (lane TTL) — acceptable
+      // at-least-once; the ledger's resolution paths still dedupe the
+      // persistent side effects.
+      await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => {});
+    }
   }
 }
 
@@ -268,7 +547,22 @@ export async function consumeMessageWorkItem(
 ): Promise<void> {
   if (host.shuttingDown) return;
   if (!host.tryClaimMessage(item.source_id)) return;
+  // Administrative drop (deleted source / self-sender / skip decision): on
+  // the ledger path the by-id complete closes the pending row terminally and
+  // refuses (409) a row a live lane owns — the owner's turn resolves it. The
+  // legacy ack remains the ledger-disabled / pre-by-id fallback.
+  // Fire-and-forget either way: a failed drop leaves the row live and the
+  // next re-drive converges on the same drop.
   const ackItem = () => {
+    if (host.laneLedger && !host.ledgerDisabled && !host.typedByIdCompleteUnsupported) {
+      void resolveDispatchByID(host, item.id).then((outcome) => {
+        if (outcome === 'unsupported') {
+          host.typedByIdCompleteUnsupported = true;
+          host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => {});
+        }
+      });
+      return;
+    }
     host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => {});
   };
 

package/src/index.ts

@@ -2,7 +2,7 @@ export * from './provider-config.js';
 export * from './types.js';
 export * from './lane-key.js';
 export type { LaneFlowHost } from './gateway-lane-flow.js';
-export { consumeTypedDispatch } from './gateway-lane-flow.js';
+export { consumeTypedDispatch, settleDrainedTypedGroup } from './gateway-lane-flow.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.js';

package/src/lane-ledger.ts

@@ -19,6 +19,13 @@ export type ActiveLane = {
   /** Lease expiry (ms epoch) and TTL from the claim — renewal pacing state. */
   leaseUntilMs?: number;
   leaseTtlMs?: number;
+  /**
+   * Sticky error bit: some turn on this lane surfaced a runtime error. Read
+   * (and only cleared) by the lane's final complete, so an error outcome
+   * survives buffered same-lane turns in between — a later successful turn
+   * must not no_action-sweep the failed turn's members.
+   */
+  turnError?: boolean;
 };
 
 /**
@@ -122,9 +129,19 @@ export class LaneLedger {
         throw err;
       }
       if (!res.claimed || !res.lane) {
-        this.opts.log?.info(
-          `lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`,
-        );
+        if (res.reason === 'empty') {
+          // Nothing foldable: resolved elsewhere, or stranded outside the
+          // ledger (the reconciler reclaims strays past the received TTL).
+          // Post-convergence this should not happen on a message lane — warn
+          // so a regression surfaces (design §3).
+          this.opts.log?.warn(
+            `claim for ${targetUri} came back empty — nothing foldable; leaving to the reconciler`,
+          );
+        } else {
+          this.opts.log?.info(
+            `lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`,
+          );
+        }
         return null;
       }
       const leaseUntilMs = Date.parse(res.lease_until ?? '');
@@ -218,6 +235,18 @@ export class LaneLedger {
    * re-drives any same-target pending work. A STALE_LANE answer means a
    * takeover already owns the resource — local state is dropped either way.
    */
+  /**
+   * Record that the turn on this lane surfaced a runtime error. The flow
+   * settles an errored lane immediately (dispatchLaneGroup returns 'failed'
+   * after a forced complete), so the bit normally lives for one turn only —
+   * it is the transport between the gateway's per-session error signal and
+   * this lane's complete request.
+   */
+  markTurnError(laneKey: string): void {
+    const lane = this.lanes.get(laneKey);
+    if (lane) lane.turnError = true;
+  }
+
   async completeIfIdle(laneKey: string, hasMoreLocal: boolean): Promise<void> {
     const lane = this.lanes.get(laneKey);
     if (!lane || hasMoreLocal) return;
@@ -228,6 +257,9 @@ export class LaneLedger {
         lane: lane.lane,
         target_uri: lane.targetUri,
         thread_root_id: lane.threadRootId,
+        // An error turn releases its members for retry instead of sweeping
+        // them as handled (ignored by older servers).
+        turn_outcome: lane.turnError ? 'error' : 'ok',
       });
       if (res.swept_no_action > 0 || res.redriven) {
         this.opts.log?.info(
@@ -244,6 +276,17 @@ export class LaneLedger {
     }
   }
 
+  /**
+   * Renew one lane by its key — the external runtime-activity hook for
+   * adapters whose tool traffic bypasses the RuntimeEvent stream (openclaw
+   * hooks). Scoped to the session's own lane: renewing every lane would let
+   * one busy fork keep an unrelated stalled fork's lane leased forever.
+   */
+  renewByKey(laneKey: string): void {
+    const lane = this.lanes.get(laneKey);
+    if (lane) this.maybeRenew(lane);
+  }
+
   /**
    * Long-turn keepalive: renew the lane's lease on runtime activity, throttled
    * so a chatty turn doesn't spam the server. Without this, a legitimately
@@ -350,6 +393,20 @@ export class LaneLedger {
     return lane;
   }
 
+  /**
+   * Drop a lane's local record without any server call — for a typed lane
+   * whose member the by-id complete just resolved (the server dropped the
+   * vacated lane row in the same transaction). Calling completeIfIdle
+   * instead would fire a lane-form Complete at a lane that no longer exists
+   * and burn an RPC on the guaranteed STALE_LANE answer.
+   */
+  dropLocal(laneKey: string): void {
+    const lane = this.lanes.get(laneKey);
+    if (!lane) return;
+    this.lanes.delete(laneKey);
+    this.removeLaneContext(lane);
+  }
+
   /**
    * Remove the per-lane context file (and its CLI sidecar) when the lane
    * ends. A leftover file would make a later cross-context send to the same

package/src/skills/parall-schedules.ts

@@ -35,7 +35,7 @@ parall schedules create \\
   --run-at <FUTURE_RFC3339_TIME>
 \`\`\`
 
-\`--target-ids\` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). \`--attached-to-uri\` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (\`cancel_reason=attached_gone\`).
+\`--target-ids\` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). \`--attached-to-uri\` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (\`status_reason=attached_gone\`). A schedule whose agent targets all sit on a terminated machine is auto-paused by the platform (\`status_reason=attendee_unreachable\`) instead of firing into a void; resuming a recurring schedule while the machine is still terminated just pauses it again on the next slot (a one-shot resumed past its catch-up window instead follows the normal missed semantics and completes).
 
 ### Reminders for someone else
 

package/src/skills/parall-tasks.ts

@@ -34,16 +34,32 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
 
-# Update task status
-parall tasks update prll://tsk_xxx --status in_progress
-parall tasks update prll://tsk_xxx --status done
+# Update task status — add --placement end so the task lands at the end of
+# its NEW status column (a bare --status keeps the old column's sort_order)
+parall tasks update prll://tsk_xxx --status in_progress --placement end
+parall tasks update prll://tsk_xxx --status done --placement end
+
+# Due date — a plain YYYY-MM-DD date (no timestamps); "none" clears it
+parall tasks update prll://tsk_xxx --due-date 2026-08-01
+parall tasks update prll://tsk_xxx --due-date none
+
+# Move a task to the end of its status column
+parall tasks update prll://tsk_xxx --placement end
 
 # Add a comment
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 \`\`\`
 
+Ordering: to append a task to the end of a status column, always use
+\`--placement end\` — the server resolves the position atomically. This
+includes status changes: a bare \`--status\` keeps the task's old
+\`sort_order\`, which may collide inside the new column. Do NOT compute a
+\`sort_order\` value yourself from listed tasks (your view may be stale or
+partial). \`--sort-order\` is only for pinpoint insertion between two cards
+you just listed, and it cannot be combined with \`--placement\`.
+
 Subtasks are just tasks with a parent: create one with \`tasks create --parent-id\`,
 re-parent with \`tasks update --parent-id\`, list a parent's children with
 \`tasks subtasks\`. \`tasks list\` without \`--parent-id\` already returns both
@@ -78,7 +94,7 @@ watcher.
 When you receive \`[Event: task.assigned]\`:
 
 1. Acknowledge with a comment: \`tasks comments add prll://tsk_xxx --body "On it"\`
-2. Update status: \`tasks update prll://tsk_xxx --status in_progress\`
+2. Update status: \`tasks update prll://tsk_xxx --status in_progress --placement end\`
 3. Do the work
 4. Report results in a comment. If a gate remains — review, merge, deploy,
    requester acceptance — set \`in_review\` and name the gate; set \`done\`

package/src/types.ts

@@ -86,7 +86,8 @@ export type ParallEvent = {
     | 'comment'
     | 'schedule_run'
     | 'external_trigger_run'
-    | 'channel_message';
+    | 'channel_message'
+    | 'approval';
   ackSourceId?: string;
   /** WorkItem id, when known (dispatch catch-up / re-drive hints carry it; live message.new does not). */
   dispatchEventId?: string;