Subchapter 1.3

Session Inspection

references/session-inspection.mdMarkdown10 KBView on GitHub

Inspect work, sessions, and memory

Read connection.md first. These recipes assume FACTORY_URL is the user’s verified target and PROJECT_ID came from that target’s Factory project list. Preserve the target and any deployment-specific auth/prefix options on every call. Never substitute a platform deployment ID for PROJECT_ID.

For platform authentication, use mastra auth whoami to identify the current user ID without reading credentials. For other auth providers, establish the actual Factory user identity with the user; don’t assume a platform user ID applies. Set USER_ID to that verified identity.

Session Inspection · Mastra Factory · mastra-ai/skills · Skills Docs

mastra api --url "$FACTORY_URL" factory work-item list "$PROJECT_ID" \
  | jq --arg user "$USER_ID" '.data | {
      runningSessionIds, parkedSessionIds,
      workItems: [.workItems[] | select(
        .createdBy == $user or any(.sessions[]?; .startedBy == $user)
      ) | {id, title, board, stages, revision, sessions, updatedAt}]
    }'

mastra api --url "$FACTORY_URL" thread --help
mastra api --url "$FACTORY_URL" thread list --schema
mastra api --url "$FACTORY_URL" thread get "$THREAD_ID" \
  | jq '.data | {id, resourceId, title, createdAt, updatedAt}'
mastra api --url "$FACTORY_URL" thread messages --schema \
  | jq '{positionals, input: .input.schema}'
mastra api --url "$FACTORY_URL" thread messages "$THREAD_ID" '{"page":0,"perPage":10}' \
  | jq '{page, messages: [.data[] | {id, role, createdAt, parts: .content.parts}]}'

mastra api --url "$FACTORY_URL" factory work-item list "$PROJECT_ID" \
  | jq -r --arg id "$WORK_ITEM_ID" --arg base "$FACTORY_URL" --arg project "$PROJECT_ID" '
      (.data.workItems // .data)[] | select(.id == $id)
      | .sessions | to_entries[]
      | "\($base)/factories/\($project)/workspaces/\(.value.sessionId)/threads/\(.value.threadId)"' \
  | sort -u
# then: open "<url>"   (macOS)  /  xdg-open "<url>"  (Linux)

mastra api --url "$FACTORY_URL" memory --help
mastra api --url "$FACTORY_URL" memory status --schema \
  | jq '{positionals, input: .input.schema}'
mastra api --url "$FACTORY_URL" agent list \
  | jq '.data[] | {id, name}'

mastra api --url "$FACTORY_URL" memory status \
  "$(jq -nc --arg agent "$AGENT_ID" --arg resource "$RESOURCE_ID" --arg thread "$THREAD_ID" \
    '{agentId:$agent,resourceId:$resource,threadId:$thread}')" \
  | jq '.data.observationalMemory'

mastra api --url "$FACTORY_URL" thread messages "$THREAD_ID" '{"page":0,"perPage":10}' \
  | jq '{page, events: [.data[] | .content.parts[]? |
      select(.type | startswith("data-om-")) |
      {type, data: (.data | {cycleId, observations, error, tokensAttempted})}]}'

Finding	Meaning / next inspection
`seat-missing`	Working-stage item has no active binding and no in-flight decision. Check whether work is already complete, intentionally parked, or awaiting a real restart. It is not itself proof of a crash and need not have an age threshold.
`seat-orphaned`	Active binding references a missing or terminal item. Inspect binding/item state before revocation.
`start-stalled`	A pending start failed or exceeded the supervisor’s stall threshold. Inspect its failure and session before restarting.
`decision-stuck`	Pending/retry decision has waited too long, or a lease has expired. Inspect status, attempts, and errors before retry.
`held-waiting`	Work is waiting for human acceptance. Check acceptance and triage state rather than launching an agent.
`label-drift`	External labels disagree with acceptance state. Inspect synchronization state.

Session Inspection

Inspect work, sessions, and memory

Session Inspection

Inspect work, sessions, and memory

Follow a work item into its thread

Open a session in the Factory UI

Observational memory (OM)

Interpret supervisor findings before suggesting repairs