@parall/agent-core 1.44.0 → 1.46.0

package/src/session-lifecycle.ts

@@ -0,0 +1,552 @@
+/**
+ * SessionLifecycleCoordinator — the single entry point for session status
+ * writes (active / idle / closed).
+ *
+ * SCOPE — this is a **process-local mitigation**, not a distributed fence.
+ * It serializes and orders the lifecycle writes THIS process issues. It does
+ * NOT order across processes, and it cannot fix a write that times out
+ * client-side but lands server-side later, nor an old turn's step retry
+ * landing during a new turn. The structural fix is a server-side turn fence
+ * (design tracked in #1879 — durable step outbox + turn fence); until that
+ * ships, this closes the in-process interleavings that produced the
+ * 2026-07-13 repro.
+ *
+ * The gateway used to fire active and idle PATCHes independently
+ * (fire-and-forget + detached retries). Two independent HTTP requests have
+ * no ordering: turn 1's in-flight idle could land AFTER turn 2's active and
+ * demote a running session — an epoch check on retry TIMERS cannot cancel a
+ * request already on the wire. The coordinator closes that class by being a
+ * serialized desired-state reconciler:
+ *
+ * - Per session it stores only the LATEST desired state plus a monotonic
+ *   generation (bumped by beginTurn and closeSession).
+ * - At most ONE lifecycle write is in flight per session; when it settles
+ *   the loop re-reads the latest desired state and reconciles — so a
+ *   begin(turn N+1), or a closeSession, that arrives while an earlier write
+ *   is in flight simply waits for it to settle and is written AFTER it.
+ * - finishTurn carries the TurnHandle from its beginTurn; a stale handle
+ *   (generation superseded) is ignored outright.
+ * - Retries re-run the reconcile loop against the LATEST desired state —
+ *   they never replay a captured command, so a pending idle retry is
+ *   naturally superseded by a new turn.
+ * - Errors are CLASSIFIED (ports, defaults are conservative): transient →
+ *   bounded backoff; permanent (4xx) → warn + abandon that desired state (a
+ *   later turn retries with a fresh generation); session-stale (the server
+ *   considers the session terminal) → drop the session, never write again.
+ * - beginTurn / closeSession resolve once one write attempt covering their
+ *   generation has SETTLED (success or failure — bounded by the write's own
+ *   timeout, plus at most one in-flight predecessor). The gateway awaits
+ *   beginTurn before persisting the turn's first AgentStep, so a reused idle
+ *   session is reconciled to active before steps arrive and the server's
+ *   presence guard cannot swallow the turn's activity. A failed active write
+ *   warns and lets the step flow continue.
+ * - closeSession's first settle carries a STRUCTURED outcome (`closed` /
+ *   `stale` / `retrying` / `permanent_failure` / `disposed`) plus a
+ *   `terminal` promise that resolves when the close reaches a terminal fate
+ *   — a caller holding cleanup behind the close (ForkSessionFinalizer) can
+ *   keep ownership through `retrying` instead of mistaking "one attempt
+ *   settled" for "close completed".
+ * - Entries are RECLAIMED (no unbounded Map growth on long-lived daemons):
+ *   dropSession removes the entry immediately when idle, or at the end of an
+ *   in-flight write; a `closed` that landed OR failed permanently reclaims
+ *   too — the permanent failure is not hidden by the reclaim, it is reported
+ *   through the close's outcome/terminal before the entry goes away.
+ * - dispose() is absorbing: every later public command is a no-op that never
+ *   re-creates an entry, issues a write, or arms a timer.
+ *
+ * The write port is infrastructure (ParallClient.updateAgentSession);
+ * retries, generations, error classification and the state machine live here.
+ */
+
+export type SessionStatusPayload =
+  | { status: 'active'; trigger_message_id?: string }
+  | { status: 'idle' }
+  | { status: 'closed' };
+
+export type TurnHandle = { sessionId: string; generation: number };
+
+/**
+ * Terminal fate of a closeSession: `closed` — the write landed; `stale` —
+ * the server already considers the session terminal (equivalent outcome for
+ * the caller); `permanent_failure` — a 4xx or retry exhaustion; the close
+ * will never be written and the server-side session may be left non-closed;
+ * `disposed` — the coordinator shut down before the close settled.
+ */
+export type SessionCloseOutcome = 'closed' | 'stale' | 'permanent_failure' | 'disposed';
+
+/** First-settle view: `retrying` means a transient failure settled the first
+ * bounded attempt and background reconciliation continues — await `terminal`
+ * for the eventual fate. */
+export type SessionCloseSettle = SessionCloseOutcome | 'retrying';
+
+export type SessionCloseResult = {
+  /** Outcome of the first bounded settle (one write attempt covering the close). */
+  outcome: SessionCloseSettle;
+  /**
+   * Resolves when the close reaches a terminal state. Already resolved (to
+   * `outcome`) unless `outcome === 'retrying'`.
+   */
+  terminal: Promise<SessionCloseOutcome>;
+};
+
+/** How one write attempt settled — the value first-settle waiters receive. */
+type WriteSettle = 'ok' | 'retry' | 'permanent' | 'stale' | 'dropped' | 'disposed';
+
+export type SessionLifecycleScheduler = {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(timer: unknown): void;
+};
+
+export type SessionLifecycleOpts = {
+  write: (sessionId: string, payload: SessionStatusPayload) => Promise<void>;
+  /**
+   * Transient failure worth retrying (timeout / network / 5xx). Anything
+   * else is treated as permanent: warn + abandon (no retry loop against a
+   * 400/401/403/404). Default: nothing is retryable — callers that want
+   * retries must classify.
+   */
+  isRetryable?: (err: unknown) => boolean;
+  /**
+   * The server considers this session terminal (409 SESSION_NOT_LIVE /
+   * INVALID_TRANSITION). The session is dropped — no further lifecycle
+   * writes, ever. Default: never stale.
+   */
+  isSessionStale?: (err: unknown) => boolean;
+  log?: { warn: (msg: string) => void };
+  /** Test port; default wraps global timers and unrefs them. */
+  scheduler?: SessionLifecycleScheduler;
+  /** Reconcile retry backoff. Default 5s→15s→45s→135s→405s (~10 min). */
+  retryDelaysMs?: number[];
+};
+
+type DesiredState = 'active' | 'idle' | 'closed';
+
+type StateStamp = { state: DesiredState; generation: number };
+
+type Entry = {
+  desired: DesiredState;
+  generation: number;
+  triggerMessageId?: string;
+  writing: boolean;
+  /** Last successfully written state. */
+  written?: StateStamp;
+  /** Permanently failed state — not retried until the desired state moves. */
+  abandoned?: StateStamp;
+  retryTimer?: unknown;
+  retryAttempt: number;
+  waiters: Array<{ generation: number; resolve: (settle: WriteSettle) => void }>;
+  /** closeSession terminal-outcome waiters — resolved exactly once each. */
+  closeWaiters: Array<{ generation: number; resolve: (outcome: SessionCloseOutcome) => void }>;
+  dropped: boolean;
+};
+
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 135_000, 405_000];
+
+const defaultScheduler: SessionLifecycleScheduler = {
+  setTimeout(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    (timer as NodeJS.Timeout).unref?.();
+    return timer;
+  },
+  clearTimeout(timer) {
+    clearTimeout(timer as NodeJS.Timeout);
+  },
+};
+
+export class SessionLifecycleCoordinator {
+  private readonly sessions = new Map<string, Entry>();
+  private readonly scheduler: SessionLifecycleScheduler;
+  private readonly retryDelays: number[];
+  // Generations are coordinator-global and strictly increasing, so a handle
+  // from before an entry was reclaimed can never match a REBUILT entry for
+  // the same session id (per-entry counters restart at 1 — an ABA hazard
+  // where a stale finish would demote a fresh turn).
+  private nextGeneration = 0;
+  private disposed = false;
+
+  constructor(private readonly opts: SessionLifecycleOpts) {
+    this.scheduler = opts.scheduler ?? defaultScheduler;
+    this.retryDelays = opts.retryDelaysMs?.length ? opts.retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
+  }
+
+  /** Sessions currently tracked — reclaimed entries are gone (leak probe). */
+  trackedSessions(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Declare a new turn. Resolves once one write attempt covering this turn's
+   * generation has settled (bounded: at most one in-flight predecessor plus
+   * one active write, each bounded by the write port's own timeout). Always
+   * resolves — a failed active write is warned and reconciled in the
+   * background, never blocks the caller.
+   */
+  async beginTurn(sessionId: string, triggerMessageId?: string): Promise<TurnHandle> {
+    // Dispose is absorbing: never touch the map (an upsert here would
+    // re-create an entry nothing will ever reclaim), never write.
+    // Generation 0 can't match any live entry, so the handle is inert.
+    if (this.disposed) return { sessionId, generation: 0 };
+    const entry = this.upsert(sessionId);
+    entry.desired = 'active';
+    entry.triggerMessageId = triggerMessageId;
+    const generation = entry.generation;
+    const settled = this.waitFor(entry, generation);
+    this.pump(sessionId);
+    await settled;
+    return { sessionId, generation };
+  }
+
+  /**
+   * Declare the turn finished. A stale handle (a newer turn — or a close —
+   * has bumped this session's generation) is ignored: finish(turn N) can
+   * never override begin(turn N+1). Reconciliation runs detached.
+   */
+  finishTurn(handle: TurnHandle): void {
+    if (this.disposed) return;
+    const entry = this.sessions.get(handle.sessionId);
+    if (!entry || entry.dropped || entry.generation !== handle.generation) return;
+    if (entry.desired === 'closed') return;
+    entry.desired = 'idle';
+    entry.retryAttempt = 0;
+    this.cancelRetry(entry);
+    this.pump(handle.sessionId);
+  }
+
+  /**
+   * Terminal transition (fork teardown). Serialized behind any in-flight
+   * write — a `closed` can never race the turn's idle — and reclaimed once
+   * settled. Resolves after one bounded settle with a STRUCTURED outcome:
+   * `closed` / `stale` / `permanent_failure` are terminal; `retrying` means
+   * background reconciliation continues — the caller keeps ownership of the
+   * session until `terminal` resolves. A close is never silently "done":
+   * every fate is observable.
+   */
+  async closeSession(sessionId: string): Promise<SessionCloseResult> {
+    if (this.disposed) {
+      return { outcome: 'disposed', terminal: Promise.resolve('disposed') };
+    }
+    const entry = this.upsert(sessionId);
+    entry.desired = 'closed';
+    entry.triggerMessageId = undefined;
+    const generation = entry.generation;
+    const terminal = new Promise<SessionCloseOutcome>((resolve) => {
+      entry.closeWaiters.push({ generation, resolve });
+    });
+    const settled = this.waitFor(entry, generation);
+    this.pump(sessionId);
+    const settle = await settled;
+    return { outcome: closeSettleFor(settle), terminal };
+  }
+
+  /**
+   * Session is dead (stale / superseded) — no further lifecycle writes, and
+   * the entry is reclaimed (immediately when idle; at the end of an in-flight
+   * write otherwise, unless a new turn revives it in the meantime).
+   */
+  dropSession(sessionId: string): void {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    entry.dropped = true;
+    this.cancelRetry(entry);
+    this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'dropped');
+    this.reclaim(sessionId, entry);
+  }
+
+  /** Every tracked session is dead (server closed them all — new_session). */
+  dropAllSessions(): void {
+    for (const sessionId of [...this.sessions.keys()]) this.dropSession(sessionId);
+  }
+
+  /**
+   * One best-effort reconcile pass over unsettled sessions within a hard
+   * deadline (shutdown). Returns the number still unsettled.
+   */
+  async flush(deadlineMs: number): Promise<number> {
+    const deadline = Date.now() + deadlineMs;
+    for (const [sessionId, entry] of [...this.sessions.entries()]) {
+      if (this.disposed) break;
+      if (entry.dropped || this.isSettled(entry)) continue;
+      this.cancelRetry(entry);
+      entry.retryAttempt = 0;
+      const timeLeft = deadline - Date.now();
+      if (timeLeft <= 0) break;
+      const settled = this.waitFor(entry, entry.generation);
+      this.pump(sessionId);
+      await raceWithDeadline(settled, timeLeft);
+    }
+    let remaining = 0;
+    for (const entry of this.sessions.values()) {
+      if (!entry.dropped && !this.isSettled(entry)) remaining += 1;
+    }
+    return remaining;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    for (const entry of this.sessions.values()) {
+      this.cancelRetry(entry);
+      this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'disposed');
+      this.settleCloseTerminal(entry, 'disposed');
+    }
+    this.sessions.clear();
+  }
+
+  // --- internals ----------------------------------------------------------
+
+  /**
+   * Get-or-create the entry and take the next generation. A dropped entry is
+   * REUSED (not replaced): its `writing` flag keeps the single-writer chain
+   * intact if a pre-drop write is still on the wire, and the generation stays
+   * monotonic across the drop boundary.
+   */
+  private upsert(sessionId: string): Entry {
+    let entry = this.sessions.get(sessionId);
+    if (!entry) {
+      entry = {
+        desired: 'active',
+        generation: 0,
+        writing: false,
+        retryAttempt: 0,
+        waiters: [],
+        closeWaiters: [],
+        dropped: false,
+      };
+      this.sessions.set(sessionId, entry);
+    }
+    entry.dropped = false;
+    this.nextGeneration += 1;
+    entry.generation = this.nextGeneration;
+    entry.retryAttempt = 0;
+    this.cancelRetry(entry);
+    return entry;
+  }
+
+  private waitFor(entry: Entry, generation: number): Promise<WriteSettle> {
+    return new Promise<WriteSettle>((resolve) => {
+      entry.waiters.push({ generation, resolve });
+    });
+  }
+
+  private isReconciled(entry: Entry): boolean {
+    return (
+      entry.written !== undefined &&
+      entry.written.state === entry.desired &&
+      entry.written.generation === entry.generation
+    );
+  }
+
+  private isAbandoned(entry: Entry): boolean {
+    return (
+      entry.abandoned !== undefined &&
+      entry.abandoned.state === entry.desired &&
+      entry.abandoned.generation === entry.generation
+    );
+  }
+
+  /** Nothing more to do for the current desired state (written or given up). */
+  private isSettled(entry: Entry): boolean {
+    return this.isReconciled(entry) || this.isAbandoned(entry);
+  }
+
+  private pump(sessionId: string): void {
+    const entry = this.sessions.get(sessionId);
+    if (!entry || entry.writing || entry.dropped || this.disposed) return;
+    if (this.isSettled(entry)) {
+      this.resolveWaiters(entry, entry.generation, this.isReconciled(entry) ? 'ok' : 'permanent');
+      this.reclaim(sessionId, entry);
+      return;
+    }
+    entry.writing = true;
+    void this.writeLoop(sessionId, entry);
+  }
+
+  private async writeLoop(sessionId: string, entry: Entry): Promise<void> {
+    try {
+      while (!entry.dropped && !this.disposed && !this.isSettled(entry)) {
+        const snapshot: StateStamp & { trigger?: string } = {
+          state: entry.desired,
+          generation: entry.generation,
+          trigger: entry.triggerMessageId,
+        };
+        let outcome: 'ok' | 'retry' | 'permanent' | 'stale' = 'ok';
+        try {
+          await this.opts.write(sessionId, payloadFor(snapshot));
+          entry.written = { state: snapshot.state, generation: snapshot.generation };
+          entry.retryAttempt = 0;
+          if (snapshot.state === 'closed') {
+            this.settleCloseTerminal(entry, 'closed', snapshot.generation);
+          }
+        } catch (err) {
+          outcome = this.classify(err);
+          this.opts.log?.warn(
+            `session ${sessionId} ${snapshot.state} write failed (${outcome}, gen ${snapshot.generation}): ${String(err)}`,
+          );
+        }
+        // A settle — success or failure — resolves every waiter this
+        // snapshot covers (the bounded beginTurn / closeSession contract).
+        this.resolveWaiters(entry, snapshot.generation, outcome);
+
+        if (outcome === 'stale') {
+          // Terminal server-side: never write to this session again.
+          entry.dropped = true;
+          this.cancelRetry(entry);
+          this.settleCloseTerminal(entry, 'stale');
+          this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'stale');
+          return;
+        }
+        const desiredUnchanged =
+          snapshot.generation === entry.generation && snapshot.state === entry.desired;
+        if (outcome === 'permanent' && desiredUnchanged) {
+          // No retry loop against a 4xx — a later turn (fresh generation)
+          // un-abandons this session automatically.
+          entry.abandoned = { state: snapshot.state, generation: snapshot.generation };
+          if (snapshot.state === 'closed') {
+            this.settleCloseTerminal(entry, 'permanent_failure', snapshot.generation);
+          }
+          return;
+        }
+        if (outcome === 'retry' && desiredUnchanged && !entry.dropped && !this.disposed) {
+          // The retry re-enters pump and replays the LATEST desired state,
+          // never this snapshot.
+          this.scheduleRetry(sessionId, entry);
+          return;
+        }
+        // Success, or the desired state advanced while writing: loop and
+        // reconcile the fresh state immediately.
+      }
+    } finally {
+      entry.writing = false;
+      this.reclaim(sessionId, entry);
+    }
+  }
+
+  private classify(err: unknown): 'retry' | 'permanent' | 'stale' {
+    if (this.opts.isSessionStale?.(err)) return 'stale';
+    if (this.opts.isRetryable?.(err)) return 'retry';
+    return 'permanent';
+  }
+
+  /**
+   * Drop the entry when it can never write again: dropped (and no write on
+   * the wire), a terminal `closed` that landed, or a `closed` that failed
+   * permanently (its fate has been reported via closeSession's outcome — an
+   * entry kept around would be an unowned leak, not a recovery path). Called
+   * after every write settles and from dropSession — this is what keeps the
+   * Map bounded on a long-lived daemon churning fork sessions.
+   */
+  private reclaim(sessionId: string, entry: Entry): void {
+    if (this.sessions.get(sessionId) !== entry) return;
+    if (entry.writing) return; // the write's finally will re-run this
+    const closedLanded =
+      entry.desired === 'closed' &&
+      entry.written?.state === 'closed' &&
+      entry.written.generation === entry.generation;
+    const closedAbandoned =
+      entry.desired === 'closed' &&
+      entry.abandoned?.state === 'closed' &&
+      entry.abandoned.generation === entry.generation;
+    if (!entry.dropped && !closedLanded && !closedAbandoned) return;
+    this.cancelRetry(entry);
+    this.settleCloseTerminal(
+      entry,
+      closedLanded ? 'closed' : entry.dropped ? 'stale' : 'permanent_failure',
+    );
+    this.resolveWaiters(
+      entry,
+      Number.POSITIVE_INFINITY,
+      closedLanded ? 'ok' : entry.dropped ? 'dropped' : 'permanent',
+    );
+    this.sessions.delete(sessionId);
+  }
+
+  private scheduleRetry(sessionId: string, entry: Entry): void {
+    if (entry.retryTimer !== undefined) return;
+    if (entry.retryAttempt >= this.retryDelays.length) {
+      this.opts.log?.warn(
+        `session ${sessionId} lifecycle reconcile giving up after ${entry.retryAttempt} retries (desired=${entry.desired})`,
+      );
+      entry.abandoned = { state: entry.desired, generation: entry.generation };
+      if (entry.desired === 'closed') {
+        this.settleCloseTerminal(entry, 'permanent_failure');
+      }
+      return;
+    }
+    const delay = this.retryDelays[entry.retryAttempt] ?? 5_000;
+    entry.retryAttempt += 1;
+    entry.retryTimer = this.scheduler.setTimeout(() => {
+      entry.retryTimer = undefined;
+      this.pump(sessionId);
+    }, delay);
+  }
+
+  private cancelRetry(entry: Entry): void {
+    if (entry.retryTimer !== undefined) {
+      this.scheduler.clearTimeout(entry.retryTimer);
+      entry.retryTimer = undefined;
+    }
+  }
+
+  private resolveWaiters(entry: Entry, upToGeneration: number, settle: WriteSettle): void {
+    if (entry.waiters.length === 0) return;
+    const remaining: Entry['waiters'] = [];
+    for (const waiter of entry.waiters) {
+      if (waiter.generation <= upToGeneration) waiter.resolve(settle);
+      else remaining.push(waiter);
+    }
+    entry.waiters = remaining;
+  }
+
+  /** Resolve closeSession terminal waiters covered by this settle, once. */
+  private settleCloseTerminal(
+    entry: Entry,
+    outcome: SessionCloseOutcome,
+    upToGeneration = Number.POSITIVE_INFINITY,
+  ): void {
+    if (entry.closeWaiters.length === 0) return;
+    const remaining: Entry['closeWaiters'] = [];
+    for (const waiter of entry.closeWaiters) {
+      if (waiter.generation <= upToGeneration) waiter.resolve(outcome);
+      else remaining.push(waiter);
+    }
+    entry.closeWaiters = remaining;
+  }
+}
+
+/** Map a first-settle write outcome onto the closeSession vocabulary. */
+function closeSettleFor(settle: WriteSettle): SessionCloseSettle {
+  switch (settle) {
+    case 'ok':
+      return 'closed';
+    case 'retry':
+      return 'retrying';
+    case 'stale':
+    case 'dropped':
+      return 'stale';
+    case 'disposed':
+      return 'disposed';
+    default:
+      return 'permanent_failure';
+  }
+}
+
+function payloadFor(snapshot: StateStamp & { trigger?: string }): SessionStatusPayload {
+  if (snapshot.state === 'active') {
+    return {
+      status: 'active',
+      ...(snapshot.trigger ? { trigger_message_id: snapshot.trigger } : {}),
+    };
+  }
+  return snapshot.state === 'idle' ? { status: 'idle' } : { status: 'closed' };
+}
+
+async function raceWithDeadline<T>(work: Promise<T>, ms: number): Promise<T | 'timeout'> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), Math.max(0, ms));
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/skills/parall-clips.ts

@@ -26,6 +26,9 @@ Results are JSON on stdout; failures print an error.
   clip's owner or an admin to bind it — do not retry or work around it.
 - If the executing runtime is offline or the call times out, report that
   plainly; do not queue, and never fabricate a result for a run that errored.
+- Hosted browser activation is handled by the CLI: it waits (bounded) while a
+  cold hosted browser starts, so if the invoke still fails, report the error —
+  do not blind-retry in a loop.
 - A clip may act through a person's real logged-in account — outward,
   irreversible, or spending actions (post, order, delete, pay) get the same
   caution as any shared-state change: confirm when intent isn't explicit.

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\`