@vellumai/assistant 0.4.26 → 0.4.30

package/docs/trusted-contact-access.md

@@ -4,16 +4,16 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 
 ## Roles
 
-| Role | Description |
-|------|-------------|
-| `guardian` | The verified owner/administrator of the assistant on a given channel. Has an active `channel_guardian_bindings` record. Approves or denies access requests. |
-| `trusted_contact` | An external user who has completed the verification flow and holds an active `assistant_ingress_members` record with `status: 'active'` and `policy: 'allow'`. |
-| `assistant` | The Vellum assistant daemon. Mediates the flow, enforces ACL, generates verification codes, and activates trusted contacts upon successful verification. |
+| Role              | Description                                                                                                                                                                                                    |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `guardian`        | The verified owner/administrator of the assistant on a given channel. Has a record in the `contacts` table with `role: 'guardian'` and an active `contact_channels` entry. Approves or denies access requests. |
+| `trusted_contact` | An external user who has completed the verification flow and holds a `contact_channels` record with `status: 'active'` and `policy: 'allow'`.                                                                  |
+| `assistant`       | The Vellum assistant daemon. Mediates the flow, enforces ACL, generates verification codes, and activates trusted contacts upon successful verification.                                                       |
 
 ## User Journey
 
 1. **Unknown user messages the assistant** on Telegram (or SMS, or any channel).
-2. **Assistant rejects the message** via the ingress ACL in `inbound-message-handler.ts`. The user has no `assistant_ingress_members` record, so the handler replies: *"Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."* and returns `{ denied: true, reason: 'not_a_member' }`.
+2. **Assistant rejects the message** via the ingress ACL in `inbound-message-handler.ts`. The user has no matching `contact_channels` record, so the handler replies: _"Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."_ and returns `{ denied: true, reason: 'not_a_member' }`.
 3. **Notification pipeline alerts the guardian.** The rejection triggers `notifyGuardianOfAccessRequest()` which creates a canonical access request and calls `emitNotificationSignal()` with `sourceEventName: 'ingress.access_request'`. The notification routes through the decision engine to all connected channels (vellum macOS app, Telegram, etc.). The guardian sees who is requesting access, including a request code for approve/reject and an `open invite flow` option to start the Trusted Contacts invite flow.
 
    **Access-request copy contract:** Every guardian-facing access-request notification must contain:
@@ -30,6 +30,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
    3. No guardian identity — the notification pipeline delivers via trusted/vellum channels even when no channel binding exists.
 
    This ensures unknown inbound access attempts always trigger guardian notification, even when the requester's source channel has no guardian binding.
+
 4. **Guardian approves the request.** The guardian responds to the notification (via Telegram inline button, macOS app, or IPC). On approval, the assistant creates a verification session via `createOutboundSession()` and generates a 6-digit verification code.
 5. **Guardian receives the verification code.** The assistant delivers the code to the guardian's verified channel (Telegram chat, SMS, etc.).
 6. **Guardian gives the code to the requester out-of-band** (in person, text message, phone call, etc.). This out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
@@ -43,25 +44,25 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 requested -> pending_guardian -> verification_pending -> active | denied | expired
 ```
 
-| State | Description | Store representation |
-|-------|-------------|---------------------|
-| `requested` | Unknown user messaged the assistant and was rejected. The system records the access attempt. | No member record exists. The rejection is logged in `channel_inbound_events`. A notification signal is emitted via `emitNotificationSignal()`. |
-| `pending_guardian` | The guardian has been notified and a decision is pending. | A `channel_guardian_approval_requests` record exists with `status: 'pending'`, `toolName: 'ingress_access_request'`. |
-| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter. | `channel_guardian_verification_challenges` record with `status: 'awaiting_response'`, identity-bound to the requester's expected channel identity. The approval request is updated to `status: 'approved'`. |
-| `active` | The requester entered the correct code. They are now a trusted contact. | `assistant_ingress_members` record with `status: 'active'`, `policy: 'allow'`. The verification session is `status: 'consumed'`. |
-| `denied` | The guardian explicitly denied the request. | The approval request has `status: 'denied'`. No member record is created (or if one existed, it remains unchanged). |
-| `expired` | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Approval request: `status: 'expired'` (set by `sweepExpiredGuardianApprovals()`). Verification session: expires naturally when `expiresAt < Date.now()`. |
+| State                  | Description                                                                                                        | Store representation                                                                                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requested`            | Unknown user messaged the assistant and was rejected. The system records the access attempt.                       | No member record exists. The rejection is logged in `channel_inbound_events`. A notification signal is emitted via `emitNotificationSignal()`.                                                              |
+| `pending_guardian`     | The guardian has been notified and a decision is pending.                                                          | A `channel_guardian_approval_requests` record exists with `status: 'pending'`, `toolName: 'ingress_access_request'`.                                                                                        |
+| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter.    | `channel_guardian_verification_challenges` record with `status: 'awaiting_response'`, identity-bound to the requester's expected channel identity. The approval request is updated to `status: 'approved'`. |
+| `active`               | The requester entered the correct code. They are now a trusted contact.                                            | `contact_channels` record with `status: 'active'`, `policy: 'allow'`. The verification session is `status: 'consumed'`.                                                                                     |
+| `denied`               | The guardian explicitly denied the request.                                                                        | The approval request has `status: 'denied'`. No member record is created (or if one existed, it remains unchanged).                                                                                         |
+| `expired`              | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Approval request: `status: 'expired'` (set by `sweepExpiredGuardianApprovals()`). Verification session: expires naturally when `expiresAt < Date.now()`.                                                    |
 
 ## Identity Binding Rules
 
 Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the `channel_guardian_verification_challenges` record when the session is created.
 
-| Channel | Identity fields | Binding behavior |
-|---------|----------------|------------------|
+| Channel  | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                                          |
+| -------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Telegram | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are set when the guardian provides the requester's Telegram identity (from the original rejected message metadata). The `identityBindingStatus` is `'bound'`. Verification requires `actorExternalUserId` or `actorChatId` to match. |
-| SMS | `expectedPhoneE164` = phone number in E.164 format | Set from the requester's phone number. Verification requires `actorExternalUserId` to match the expected phone. |
-| Voice | `expectedPhoneE164` = phone number in E.164 format | Same as SMS: phone-based identity binding. |
-| HTTP API | `expectedExternalUserId` = API caller identity | Bound to whatever external user ID the API client provides. |
+| SMS      | `expectedPhoneE164` = phone number in E.164 format                               | Set from the requester's phone number. Verification requires `actorExternalUserId` to match the expected phone.                                                                                                                           |
+| Voice    | `expectedPhoneE164` = phone number in E.164 format                               | Same as SMS: phone-based identity binding.                                                                                                                                                                                                |
+| HTTP API | `expectedExternalUserId` = API caller identity                                   | Bound to whatever external user ID the API client provides.                                                                                                                                                                               |
 
 **Anti-oracle invariant:** When identity verification fails, the error message is identical to the "invalid or expired code" message. This prevents attackers from distinguishing between a wrong code and a wrong identity, which would leak information about which identities have pending sessions.
 
@@ -75,49 +76,49 @@ Identity binding ensures the verification code can only be consumed by the inten
 
 ### Stage: `pending_guardian` (guardian notified, awaiting decision)
 
-| Store | Table | Record |
-|-------|-------|--------|
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | `status: 'pending'`, `toolName: 'ingress_access_request'`, `requesterExternalUserId`, `requesterChatId`, `guardianExternalUserId`, `guardianChatId` (resolved from active `channel_guardian_bindings`), `expiresAt` (GUARDIAN_APPROVAL_TTL_MS from now). |
-| `notification_events` | `notification_events` | Event with `sourceEventName: 'ingress.access_request'`, links to the conversation. |
-| `notification_decisions` | `notification_decisions` | Decision engine output: which channels to notify, confidence, reasoning. |
-| `notification_deliveries` | `notification_deliveries` | Per-channel delivery records (Telegram, vellum, etc.). |
+| Store                       | Table                                | Record                                                                                                                                                                                                                                                                                   |
+| --------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | `status: 'pending'`, `toolName: 'ingress_access_request'`, `requesterExternalUserId`, `requesterChatId`, `guardianExternalUserId`, `guardianChatId` (resolved from the `contacts`/`contact_channels` tables where `role = 'guardian'`), `expiresAt` (GUARDIAN_APPROVAL_TTL_MS from now). |
+| `notification_events`       | `notification_events`                | Event with `sourceEventName: 'ingress.access_request'`, links to the conversation.                                                                                                                                                                                                       |
+| `notification_decisions`    | `notification_decisions`             | Decision engine output: which channels to notify, confidence, reasoning.                                                                                                                                                                                                                 |
+| `notification_deliveries`   | `notification_deliveries`            | Per-channel delivery records (Telegram, vellum, etc.).                                                                                                                                                                                                                                   |
 
 ### Stage: `verification_pending` (guardian approved, code issued)
 
-| Store | Table | Record |
-|-------|-------|--------|
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'approved'`, `decidedByExternalUserId` set. |
+| Store                       | Table                                      | Record                                                                                                                                                                                                                                                                              |
+| --------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests`       | Updated to `status: 'approved'`, `decidedByExternalUserId` set.                                                                                                                                                                                                                     |
 | `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | New record: `status: 'awaiting_response'`, `identityBindingStatus: 'bound'`, `expectedExternalUserId`/`expectedChatId`/`expectedPhoneE164` set to the requester's identity, `challengeHash` = SHA-256 of the 6-digit code, `expiresAt` = 10 minutes from creation, `codeDigits: 6`. |
 
 ### Stage: `active` (code verified, trusted contact created)
 
-| Store | Table | Record |
-|-------|-------|--------|
-| `ingress-member-store.ts` | `assistant_ingress_members` | Upserted via `upsertMember()`: `status: 'active'`, `policy: 'allow'`, `sourceChannel`, `externalUserId`, `externalChatId`, `displayName`, `username`. |
-| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set. |
-| `channel-guardian-store.ts` | `channel_guardian_rate_limits` | Reset via `resetRateLimit()` on successful verification. |
+| Store                       | Table                                      | Record                                                                                                                                                                                              |
+| --------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contacts-write.ts`         | `contacts` / `contact_channels`            | Upserted via `upsertMember()`: creates a contact record and a `contact_channels` entry with `status: 'active'`, `policy: 'allow'`, channel type, `externalUserId`, `externalChatId`, `displayName`. |
+| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set.                                                                                                                |
+| `channel-guardian-store.ts` | `channel_guardian_rate_limits`             | Reset via `resetRateLimit()` on successful verification.                                                                                                                                            |
 
 ### Stage: `denied` (guardian rejected)
 
-| Store | Table | Record |
-|-------|-------|--------|
+| Store                       | Table                                | Record                                                        |
+| --------------------------- | ------------------------------------ | ------------------------------------------------------------- |
 | `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'denied'`, `decidedByExternalUserId` set. |
 
 No member record is created. No verification session is created.
 
 ### Stage: `expired`
 
-| Store | Table | Record |
-|-------|-------|--------|
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'expired'` by `sweepExpiredGuardianApprovals()` (runs every 60s). |
+| Store                       | Table                                      | Record                                                                                            |
+| --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests`       | Updated to `status: 'expired'` by `sweepExpiredGuardianApprovals()` (runs every 60s).             |
 | `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingChallengeByHash()`. |
 
 ### Invites (alternative path)
 
-The `assistant_ingress_invites` table supports a parallel invite-based onboarding path. An invite carries a SHA-256 hashed token and can be redeemed via `redeemInvite()`, which atomically creates an active member record. This path is distinct from the trusted contact flow but serves the same end state: an active member in `assistant_ingress_members`.
+The `assistant_ingress_invites` table supports a parallel invite-based onboarding path. An invite carries a SHA-256 hashed token and can be redeemed via `redeemInvite()`, which atomically creates an active contact channel record. This path is distinct from the trusted contact flow but serves the same end state: an active `contact_channels` entry with `status: 'active'` and `policy: 'allow'`.
 
-| Table | Purpose in trusted contact flow |
-|-------|--------------------------------|
+| Table                       | Purpose in trusted contact flow                                                                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `assistant_ingress_invites` | Not used in the guardian-mediated flow. Available as an alternative for direct invite links (e.g., guardian shares a URL instead of going through the approval + verification flow). |
 
 ### Voice In-Call Guardian Approval (friend-initiated)
@@ -125,6 +126,7 @@ The `assistant_ingress_invites` table supports a parallel invite-based onboardin
 Voice calls have a dedicated in-call guardian approval flow that differs from the text-channel flow. Since the caller is actively on the line, the voice flow captures the caller's name, creates a canonical access request, and holds the call while awaiting the guardian's decision.
 
 **Flow:**
+
 1. Unknown caller dials in. `relay-server.ts` resolves trust — caller is `unknown`, no pending challenge, no active invite.
 2. Relay enters `awaiting_name` state and prompts the caller for their name (with a timeout).
 3. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian.
@@ -135,10 +137,10 @@ Voice calls have a dedicated in-call guardian approval flow that differs from th
 
 **Key difference from text-channel flow:** Voice approvals skip the verification session step because the caller's phone identity is already known from the active call. Text-channel approvals still mint a 6-digit verification code for out-of-band identity confirmation.
 
-| Store | Table | Record |
-|-------|-------|--------|
-| `canonical-guardian-store.ts` | `canonical_guardian_requests` | `kind: 'access_request'`, `status: 'pending'` -> `'approved'` or `'denied'` |
-| `ingress-member-store.ts` | `assistant_ingress_members` | On approval: upserted with `status: 'active'`, `policy: 'allow'` |
+| Store                         | Table                           | Record                                                                                |
+| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
+| `canonical-guardian-store.ts` | `canonical_guardian_requests`   | `kind: 'access_request'`, `status: 'pending'` -> `'approved'` or `'denied'`           |
+| `contacts-write.ts`           | `contacts` / `contact_channels` | On approval: upserted via `upsertMember()` with `status: 'active'`, `policy: 'allow'` |
 
 ## Sequence Diagram
 
@@ -278,5 +280,5 @@ sequenceDiagram
 
 ### Anti-oracle design
 
-- All failure messages (wrong code, expired code, identity mismatch, rate-limited) return the same generic text: *"The verification code is invalid or has expired."*
+- All failure messages (wrong code, expired code, identity mismatch, rate-limited) return the same generic text: _"The verification code is invalid or has expired."_
 - This prevents attackers from distinguishing between failure modes, which could leak information about valid codes, valid identities, or rate-limit state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.26",
+  "version": "0.4.30",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"
@@ -23,11 +23,11 @@
     "test:coverage": "COVERAGE=true bash scripts/test.sh",
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bash scripts/test.sh",
     "test:bench": "find src/__tests__ -maxdepth 1 -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
-    "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh"
+    "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
+    "postinstall": "cd .. && git config core.hooksPath .githooks 2>/dev/null || true"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.42",
-    "@vellumai/proxy-sidecar": "file:../proxy-sidecar",
     "@anthropic-ai/sdk": "^0.39.0",
     "@google/genai": "^1.40.0",
     "@modelcontextprotocol/sdk": "^1.15.1",

package/scripts/compare-benchmarks.sh

@@ -2,13 +2,18 @@
 set -uo pipefail
 
 # ---------------------------------------------------------------------------
-# Compare current benchmark results against a baseline and alert on >10%
-# regressions. Exits non-zero if any benchmark regressed beyond the threshold.
+# Compare current benchmark results against a baseline and alert on
+# regressions. A regression is flagged when BOTH the percentage increase
+# exceeds the threshold (default 10%) AND the absolute increase exceeds
+# the minimum (default 50ms). Exits non-zero if any benchmark regressed.
 #
 # Usage: compare-benchmarks.sh <baseline.json> <current.json>
 # ---------------------------------------------------------------------------
 
 THRESHOLD="${BENCHMARK_REGRESSION_THRESHOLD:-10}"
+# Minimum absolute increase (ms) required to flag a regression. Filters noise
+# from fast benchmarks where small absolute swings produce large percentages.
+MIN_ABS_MS="${BENCHMARK_MIN_ABSOLUTE_MS:-50}"
 
 if [[ $# -lt 2 ]]; then
   echo "Usage: $0 <baseline.json> <current.json>"
@@ -28,7 +33,7 @@ if [[ ! -f "${CURRENT}" ]]; then
   exit 1
 fi
 
-echo "Comparing benchmarks (regression threshold: ${THRESHOLD}%)"
+echo "Comparing benchmarks (regression threshold: ${THRESHOLD}%, min absolute: ${MIN_ABS_MS}ms)"
 echo "Baseline commit: $(jq -r '.commit // "unknown"' "${BASELINE}")"
 echo "Current commit:  $(jq -r '.commit // "unknown"' "${CURRENT}")"
 echo ""
@@ -57,8 +62,10 @@ while IFS= read -r file; do
   # Uses -v to pass shell variables safely (prevents awk code injection via crafted values)
   pct_change=$(awk -v c="$current_ms" -v b="$baseline_ms" 'BEGIN { printf "%.1f", (c - b) / b * 100 }')
 
-  if awk -v p="$pct_change" -v t="$THRESHOLD" 'BEGIN { exit !(p > t) }'; then
-    echo "  REGR ${file}: ${baseline_ms}ms -> ${current_ms}ms (+${pct_change}%)"
+  abs_change=$(( current_ms - baseline_ms ))
+
+  if awk -v p="$pct_change" -v t="$THRESHOLD" 'BEGIN { exit !(p > t) }' && [[ ${abs_change} -ge ${MIN_ABS_MS} ]]; then
+    echo "  REGR ${file}: ${baseline_ms}ms -> ${current_ms}ms (+${pct_change}%, +${abs_change}ms)"
     regressions=$((regressions + 1))
   elif awk -v p="$pct_change" -v t="$THRESHOLD" 'BEGIN { exit !(p < -t) }'; then
     echo "  IMPR ${file}: ${baseline_ms}ms -> ${current_ms}ms (${pct_change}%)"

package/scripts/ipc/check-swift-decoder-drift.ts

@@ -49,9 +49,8 @@ const SWIFT_OMIT_ALLOWLIST = new Set<string>([
   "heartbeat_alert",
   // Guardian verification — daemon-internal for Telegram channel setup
   "guardian_verification_response",
-  // Ingress invite/member management — not yet consumed by the macOS client
-  "ingress_invite_response",
-  "ingress_member_response",
+  // Contacts invite management — not yet consumed by the macOS client
+  "contacts_invite_response",
   // Inbox escalation — not yet consumed by the macOS client
   "assistant_inbox_escalation_response",
   // Work item messages — not yet consumed by the macOS client
@@ -60,6 +59,9 @@ const SWIFT_OMIT_ALLOWLIST = new Set<string>([
   "work_item_status_changed",
   "work_item_update_response",
   "work_items_list_response",
+  // Contact management — not yet consumed by the macOS client
+  "contacts_response",
+  "contacts_changed",
 ]);
 
 /**

package/scripts/test.sh

@@ -18,6 +18,12 @@ set -uo pipefail
 EXCLUDE_EXPERIMENTAL="${EXCLUDE_EXPERIMENTAL:-false}"
 WORKERS="${TEST_WORKERS:-$(sysctl -n hw.logicalcpu 2>/dev/null || nproc 2>/dev/null || echo 8)}"
 COVERAGE="${COVERAGE:-false}"
+# Per-test timeout (seconds). Kills bun processes that pass but don't exit due to open handles.
+PER_TEST_TIMEOUT="${PER_TEST_TIMEOUT:-120}"
+# Longest-first scheduling: provide a durations file from a previous run to sort
+# slow tests to the front, improving parallel utilization.
+TEST_DURATIONS_FILE="${TEST_DURATIONS_FILE:-}"
+TEST_DURATIONS_OUTPUT="${TEST_DURATIONS_OUTPUT:-}"
 
 EXPERIMENTAL_FILES=(
   "skill-load-tool.test.ts"
@@ -53,6 +59,40 @@ if [[ ${#test_files[@]} -eq 0 ]]; then
   exit 1
 fi
 
+# Sort tests longest-first using durations from a previous run.
+# This ensures slow tests start immediately across all workers instead of
+# piling up at the end and becoming long poles.
+if [[ -n "${TEST_DURATIONS_FILE}" && -f "${TEST_DURATIONS_FILE}" ]]; then
+  sorted_files=()
+  # Build lookup: basename -> duration_ms
+  declare -A dur_map
+  while IFS=$'\t' read -r ms name; do
+    dur_map["${name}"]="${ms}"
+  done < "${TEST_DURATIONS_FILE}"
+
+  # Partition into known (with durations) and unknown
+  known=()
+  unknown=()
+  for f in "${test_files[@]}"; do
+    base="$(basename "${f}")"
+    if [[ -n "${dur_map["${base}"]:-}" ]]; then
+      known+=("${dur_map["${base}"]}"$'\t'"${f}")
+    else
+      unknown+=("${f}")
+    fi
+  done
+
+  # Sort known by duration descending
+  while IFS= read -r line; do
+    sorted_files+=("${line#*$'\t'}")
+  done < <(printf '%s\n' "${known[@]}" | sort -t$'\t' -k1 -rn)
+
+  # Append unknown files at the end
+  sorted_files+=("${unknown[@]}")
+  test_files=("${sorted_files[@]}")
+  echo "Sorted tests longest-first using ${TEST_DURATIONS_FILE} (${#known[@]} known, ${#unknown[@]} new)"
+fi
+
 echo "Running ${#test_files[@]} test files (${WORKERS} workers)"
 
 # Temp dir for per-file output capture and failure tracking
@@ -72,6 +112,7 @@ printf '%s\n' "${test_files[@]}" | xargs -P "${WORKERS}" -I {} bash -c '
   results_dir="$2"
   exclude_exp="$3"
   coverage_enabled="$4"
+  per_test_timeout="$5"
 
   safe_name="$(echo "${test_file}" | tr "/" "_")"
   out_file="${results_dir}/${safe_name}.out"
@@ -83,12 +124,28 @@ printf '%s\n' "${test_files[@]}" | xargs -P "${WORKERS}" -I {} bash -c '
     coverage_args="--coverage --coverage-reporter=lcov --coverage-dir=${cov_dir}"
   fi
 
+  # Resolve timeout binary (coreutils `timeout` on Linux, `gtimeout` on macOS via brew)
+  timeout_cmd=""
+  if command -v timeout &>/dev/null; then
+    timeout_cmd="timeout"
+  elif command -v gtimeout &>/dev/null; then
+    timeout_cmd="gtimeout"
+  fi
+
   start_ms=$(perl -MTime::HiRes=time -e "printf \"%d\", time*1000")
 
-  if [[ "${exclude_exp}" == "true" ]]; then
-    bun test ${coverage_args} --test-name-pattern "^(?!.*\\[experimental\\])" "${test_file}" > "${out_file}" 2>&1
+  if [[ -n "${timeout_cmd}" ]]; then
+    if [[ "${exclude_exp}" == "true" ]]; then
+      "${timeout_cmd}" -k 10 "${per_test_timeout}" bun test ${coverage_args} --test-name-pattern "^(?!.*\\[experimental\\])" "${test_file}" > "${out_file}" 2>&1
+    else
+      "${timeout_cmd}" -k 10 "${per_test_timeout}" bun test ${coverage_args} "${test_file}" > "${out_file}" 2>&1
+    fi
   else
-    bun test ${coverage_args} "${test_file}" > "${out_file}" 2>&1
+    if [[ "${exclude_exp}" == "true" ]]; then
+      bun test ${coverage_args} --test-name-pattern "^(?!.*\\[experimental\\])" "${test_file}" > "${out_file}" 2>&1
+    else
+      bun test ${coverage_args} "${test_file}" > "${out_file}" 2>&1
+    fi
   fi
   exit_code=$?
 
@@ -96,13 +153,32 @@ printf '%s\n' "${test_files[@]}" | xargs -P "${WORKERS}" -I {} bash -c '
   elapsed=$(( end_ms - start_ms ))
 
   base="$(basename "${test_file}")"
-  if [[ ${exit_code} -ne 0 ]]; then
+
+  # Record duration for longest-first scheduling in future runs
+  echo -e "${elapsed}\t${base}" >> "${results_dir}/durations"
+
+  if [[ -n "${timeout_cmd}" && ( ${exit_code} -eq 124 || ${exit_code} -eq 137 ) ]]; then
+    # timeout killed the process — check if all tests actually passed.
+    # Bun test outputs "(fail)" for failed tests and a final summary line
+    # "Ran X tests across Y files" when the run completes. Both conditions
+    # must hold: no failures AND the end-of-run summary present. Without
+    # the summary, the process was killed mid-run before finishing all tests.
+    if grep -q "^(fail)" "${out_file}" 2>/dev/null; then
+      echo "${test_file}" >> "${results_dir}/failures"
+      echo "  ✗ ${base} (killed after ${per_test_timeout}s — tests failed and process hung)"
+    elif grep -qE "^Ran [0-9]+ tests? across" "${out_file}" 2>/dev/null; then
+      echo "  ⚠ ${base} (tests passed but process hung after ${per_test_timeout}s — likely open handles)"
+    else
+      echo "${test_file}" >> "${results_dir}/failures"
+      echo "  ✗ ${base} (killed after ${per_test_timeout}s — test run did not complete)"
+    fi
+  elif [[ ${exit_code} -ne 0 ]]; then
     echo "${test_file}" >> "${results_dir}/failures"
     echo "  ✗ ${base} (${elapsed}ms)"
   else
     echo "  ✓ ${base} (${elapsed}ms)"
   fi
-' _ {} "${results_dir}" "${EXCLUDE_EXPERIMENTAL}" "${COVERAGE}"
+' _ {} "${results_dir}" "${EXCLUDE_EXPERIMENTAL}" "${COVERAGE}" "${PER_TEST_TIMEOUT}"
 xargs_exit=$?
 
 # Verify tests actually ran — catch xargs startup failures (e.g. invalid TEST_WORKERS)
@@ -118,6 +194,14 @@ if [[ ${xargs_exit} -ge 125 ]]; then
   exit 1
 fi
 
+# Write observed durations for longest-first scheduling in future CI runs.
+# This must happen before the failure exit so durations are persisted even when
+# tests fail, aligning with the `if: always()` cache save step in CI.
+if [[ -n "${TEST_DURATIONS_OUTPUT}" && -f "${results_dir}/durations" ]]; then
+  sort -t$'\t' -k1 -rn "${results_dir}/durations" > "${TEST_DURATIONS_OUTPUT}"
+  echo "Wrote test durations to ${TEST_DURATIONS_OUTPUT}"
+fi
+
 # Print output for any failed tests
 if [[ -f "${results_dir}/failures" ]]; then
   echo ""

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -30,6 +30,15 @@ exports[`IPC message snapshots ClientMessage types confirmation_response seriali
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types contacts serializes to expected JSON 1`] = `
+{
+  "action": "list",
+  "limit": 50,
+  "role": "guardian",
+  "type": "contacts",
+}
+`;
+
 exports[`IPC message snapshots ClientMessage types session_list serializes to expected JSON 1`] = `
 {
   "type": "session_list",
@@ -451,6 +460,13 @@ exports[`IPC message snapshots ClientMessage types app_open_request serializes t
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types app_delete serializes to expected JSON 1`] = `
+{
+  "appId": "app-001",
+  "type": "app_delete",
+}
+`;
+
 exports[`IPC message snapshots ClientMessage types apps_list serializes to expected JSON 1`] = `
 {
   "type": "apps_list",
@@ -951,28 +967,14 @@ exports[`IPC message snapshots ClientMessage types dictation_request serializes
 }
 `;
 
-exports[`IPC message snapshots ClientMessage types ingress_invite serializes to expected JSON 1`] = `
+exports[`IPC message snapshots ClientMessage types contacts_invite serializes to expected JSON 1`] = `
 {
   "action": "create",
   "expiresInMs": 86400000,
   "maxUses": 5,
   "note": "Test invite",
   "sourceChannel": "telegram",
-  "type": "ingress_invite",
-}
-`;
-
-exports[`IPC message snapshots ClientMessage types ingress_member serializes to expected JSON 1`] = `
-{
-  "action": "upsert",
-  "displayName": "Test User",
-  "externalChatId": "chat-456",
-  "externalUserId": "user-123",
-  "policy": "allow",
-  "sourceChannel": "telegram",
-  "status": "active",
-  "type": "ingress_member",
-  "username": "testuser",
+  "type": "contacts_invite",
 }
 `;
 
@@ -1270,6 +1272,20 @@ exports[`IPC message snapshots ServerMessage types confirmation_state_changed se
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types contacts_response serializes to expected JSON 1`] = `
+{
+  "contacts": [],
+  "success": true,
+  "type": "contacts_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types contacts_changed serializes to expected JSON 1`] = `
+{
+  "type": "contacts_changed",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types assistant_activity_state serializes to expected JSON 1`] = `
 {
   "activityVersion": 1,
@@ -1928,6 +1944,15 @@ exports[`IPC message snapshots ServerMessage types trust_rules_list_response ser
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types schedule_thread_created serializes to expected JSON 1`] = `
+{
+  "conversationId": "conv-sched-001",
+  "scheduleJobId": "sched-job-001",
+  "title": "Daily standup reminder",
+  "type": "schedule_thread_created",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types schedules_list_response serializes to expected JSON 1`] = `
 {
   "schedules": [
@@ -2064,6 +2089,13 @@ exports[`IPC message snapshots ServerMessage types shared_apps_list_response ser
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types app_delete_response serializes to expected JSON 1`] = `
+{
+  "success": true,
+  "type": "app_delete_response",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types shared_app_delete_response serializes to expected JSON 1`] = `
 {
   "success": true,
@@ -2798,7 +2830,7 @@ exports[`IPC message snapshots ServerMessage types dictation_response serializes
 }
 `;
 
-exports[`IPC message snapshots ServerMessage types ingress_invite_response serializes to expected JSON 1`] = `
+exports[`IPC message snapshots ServerMessage types contacts_invite_response serializes to expected JSON 1`] = `
 {
   "invite": {
     "createdAt": 1700000000,
@@ -2813,26 +2845,7 @@ exports[`IPC message snapshots ServerMessage types ingress_invite_response seria
     "useCount": 0,
   },
   "success": true,
-  "type": "ingress_invite_response",
-}
-`;
-
-exports[`IPC message snapshots ServerMessage types ingress_member_response serializes to expected JSON 1`] = `
-{
-  "member": {
-    "createdAt": 1700000000,
-    "displayName": "Test User",
-    "externalChatId": "chat-456",
-    "externalUserId": "user-123",
-    "id": "mem-001",
-    "lastSeenAt": 1700000000,
-    "policy": "allow",
-    "sourceChannel": "telegram",
-    "status": "active",
-    "username": "testuser",
-  },
-  "success": true,
-  "type": "ingress_member_response",
+  "type": "contacts_invite_response",
 }
 `;
 

package/src/__tests__/access-request-decision.test.ts

@@ -92,7 +92,6 @@ const GUARDIAN_APPROVAL_TTL_MS = 5 * 60 * 1000;
 function resetState(): void {
   const db = getDb();
   db.run("DELETE FROM channel_guardian_approval_requests");
-  db.run("DELETE FROM channel_guardian_bindings");
   db.run("DELETE FROM channel_guardian_verification_challenges");
   deliverReplyCalls.length = 0;
 }

package/src/__tests__/account-registry.test.ts

@@ -45,7 +45,7 @@ const _ctx: ToolContext = {
   workingDir: "/tmp",
   sessionId: "test-session",
   conversationId: "test-conv",
-  guardianTrustClass: "guardian",
+  trustClass: "guardian",
 };
 
 afterAll(() => {