This page is for technical users and operators running documentation, coding, operations, or troubleshooting work with Buffaly. Use it when you need to continue a previous session, supervise child sessions, preserve evidence, understand Plan and Scratch state, recover after compaction or worker recycle, or verify that queued work is actually progressing.
Quick answer
When work may resume later, ask Buffaly to preserve the route, evidence, and deliverables. Give it the target, the state surfaces to inspect, and the finish criteria.
Continue the wiki migration session. Preserve the route and evidence. Reread the target article, the current Plan, Scratch notes, and any durable task artifact. Summarize the last completed step before acting. Validate the absolute target path before editing. Show scoped git status for the target. Take the next safe migration step, validate the result, and if it is ready commit only the intended wiki file with a focused message.
What Buffaly should do
- Identify the session or task being continued.
- Inspect Plan, Scratch, task artifacts, timeline, target files, and git state as needed.
- Avoid repeated discovery unless the route, repo, session, or target state is stale.
How it should finish
- Take the next safe step, not a broad restart.
- Validate with concrete evidence.
- Final answer only when complete or clearly blocked.
Core mental model
Session
The container for a conversation, state, turns, tools, artifacts, child sessions, and runtime status.
Timeline and turn
The timeline is the ordered record. A turn is one user, agent, tool, or system step inside that record.
Artifact
A durable output such as a task file, report, saved summary, screenshot, diff, validation log, or generated file.
Plan, Scratch, task artifacts
Plan tracks the active route, Scratch holds working notes, and task artifacts preserve durable scope, decisions, evidence, and acceptance criteria.
Compaction
Timeline housekeeping that reduces context size while preserving typed state and active work. It is not the same as forgetting the task.
Child sessions and subagents
Bounded execution sessions delegated from a parent. The parent remains responsible for integration, validation, and final reporting.
User and Buffaly responsibilities
| User action | What Buffaly should do | How to verify |
|---|---|---|
| Start long-running work | Create a route, define deliverables, identify evidence, and keep progress in Plan or a durable task. | Plan names the next step, target path, validation, and stop condition. |
| Continue | Find the prior session, summarize the last completed step, then continue from current state. | Buffaly cites the session or task and shows what changed since the last step. |
| Preserve evidence | Save important outputs as artifacts or committed files instead of leaving them only in chat. | Artifact path, file path, commit hash, or timeline entry is named. |
| Delegate | Create bounded child work with target, source, working directory, provider or model, and expected output. | Child key, status, deliverable, and parent integration step are visible. |
| Recover | Inspect session state, Plan, Scratch, artifacts, timeline, logs, and git before editing. | Recovery answer lists evidence inspected and the next safe action. |
| Finish | Validate deliverables, report files or artifacts, name gaps, and commit only intended work when requested. | Final includes validation evidence, scoped status, and commit hash when applicable. |
Plan, Scratch, task artifact layer
Use the right surface for the job. The goal is not to write everything everywhere; it is to keep enough state durable that the next operator can continue without guessing.
| Layer | Purpose | Use for | Do not use for |
|---|---|---|---|
| Plan | Current route and next steps. | Active checklist, blocker, validation target. | Permanent requirements or long evidence dumps. |
| Scratch | Working notes and investigation breadcrumbs. | Findings, hypotheses, temporary references. | Final acceptance criteria or source of truth. |
| Task artifacts | Durable task scope, decisions, evidence, and done criteria. | Handoffs, approvals, restarts, audit trail. | Noisy per-turn transcript copies. |
| Timeline | Ordered evidence of turns, tools, actions, and results. | Finding what happened and when. | A polished deliverable by itself. |
| Artifacts | Saved outputs that need to outlive the conversation. | Summaries, reports, diffs, logs, screenshots, generated files. | Unverified conclusions or hidden state. |
Update Plan with the current route, blocker, next validation step, and stop condition. Put investigation notes in Scratch, not in the final answer.
Create a durable task artifact with scope, target paths, source evidence, acceptance criteria, and the latest verified state.
Timelines, turns, and artifacts
Long turns often include action and entity discovery, tool loading, file reads, searches, edits, validation, scoped git status, and final answers. If an output matters later, preserve it as an artifact or committed file instead of relying on conversation memory.
Save a summary
Save a summary artifact with decisions, target files, validation evidence, and remaining work.
Show evidence
Show timeline evidence for the last completed edit, validation, or child result before continuing.
Confirm durability
Confirm whether the result is in a file, artifact, commit, or conversation-only state.
Continuing previous work
Do not ask Buffaly to restart discovery when the route is still valid. Ask it to summarize the last completed step, revalidate stale repo, session, and target state, then continue from there.
Continue from session [session key]. Inspect Plan, Scratch, task artifacts, target files, timeline evidence, and scoped git status. Do not redo discovery unless a source is stale. Tell me the last completed step before making the next edit.
Before editing, revalidate the absolute target path, latest repo status, and whether any queued turns or child sessions are still running.
Child sessions and subagents
Use child sessions for bounded deliverables or specialized execution. The parent session should assign the work clearly, monitor status, collect the result, validate it, and integrate only what is ready.
Useful source contract fields
At a user-facing level, child session evidence should make it possible to identify ids, labels, source keys, child keys, working directory, provider, model, queued turns, status, and errors. You do not need every internal field in a final answer, but you should be able to verify the child result and its source.
Good use cases
- Search one area while the parent edits another.
- Run focused validation or investigate a bounded failure.
- Prepare a report or artifact for parent review.
Verification prompts
- Show the child key, source session, status, and deliverable path.
- Summarize the child output and what the parent validated before integrating it.
Workers, queued input, watchers, and lifecycle
Sessions can run through workers, and runtime status or queued input may be observable while work is still active. Before sending repeated follow-ups, ask Buffaly to check session status, queued count, and timeline events.
Use session tools before hand-editing storage. Worker recycle auto-resume is a design expectation, but the practical rule is to verify runtime state before assuming a session resumed, stalled, or completed.
Level2 watchers supervise a source session. A common key pattern is {sourceSessionKey}-level-two. Watchers may respond to turn.completed events through the default handler action tool:ToDispatchSupervisoryEvent. Verify the source session and watcher before assuming work is stuck or complete, and verify any auto-attach feature in runtime state before relying on it.
Compaction
Compaction is timeline housekeeping, not forgetting. It reduces conversation weight while preserving typed snapshots and active turn state so work can continue after context is compressed.
Verified concepts
Compaction uses thresholds such as MaxConversationTokens, TriggerTokens, TargetFreeTokens, and TargetConversationTokens, with a CompactionEngine coordinating deterministic compaction over typed snapshots.
Provider kinds
Provider kinds may include LocalAutomatic, LocalManual, ResponsesApi, and CodexApi. Verify the configured provider instead of assuming which one ran.
State preservation
Active turns should be preserved. Archive snapshots, compaction epochs, and token reset evidence help explain what changed.
Prompts
Before compaction, save the route, target files, latest validation, and next step. After compaction, show the archive or epoch, summarize preserved active work, and continue from the saved route.
Recovery patterns
When a session stalls, compacts, recycles, or loses visible progress, recover in evidence order. The point is to anchor the next action before editing.
- Exact target path and session key.
- Plan.
- Scratch.
- Durable task artifact.
- Target files and saved artifacts.
- Timeline and tool evidence.
- C:\logs\Buffaly logs.
- Scoped git status and latest relevant commits.
Recover this session before editing. Show the session key, Plan, Scratch, durable task artifact, target path, timeline evidence, relevant Buffaly logs, scoped git status, and latest commit that touched the target. Then tell me the next safe step.
Verify progress
- Which files or source documents were inspected?
- What does Plan say, and is there a blocker?
- Are Scratch notes current?
- Is there a durable task path?
- Does the exact target exist?
- Which artifacts were saved?
- What is the session status and queued count?
- Is there a compaction archive or epoch?
- What child or subagent key produced the result?
- Is a Level2 watcher attached?
- What did the session tool or status result show?
- What does scoped git status show, and is there a commit hash?
Common mistakes
Restarting valid work
Do not repeat discovery when the existing route, target, and evidence are still valid. Revalidate stale state and continue.
Leaving evidence in chat only
Important results should become artifacts, committed files, validation logs, or named timeline evidence.
Trusting child output blindly
A child session result still needs parent review, integration, validation, and a clear final report.
Assuming stuck or complete
Check session status, queued turns, worker state, watchers, timeline events, logs, and artifacts before deciding.
Troubleshooting quick reference
| Symptom | First checks | Good next prompt |
|---|---|---|
| Stuck work | Session status, queued count, latest timeline turn, worker logs. | Check status and queued turns before adding follow-up input. |
| Missing child result | Child key, source session, status, error, artifact path. | Find the child session result and show its deliverable or error. |
| Watcher confusion | Source key, Level2 key, turn.completed event, handler action. | Verify the watcher source and whether it handled the latest turn. |
| Stale context | Plan, Scratch, target file mtime, git status, latest commits. | Revalidate state and continue without repeating valid discovery. |
| Too-long session | Compaction thresholds, epoch, archive snapshot, active turn. | Summarize route and evidence, compact if needed, then resume. |
| File or commit missing | Absolute target path, artifact path, scoped git status, latest commits. | Show where the deliverable exists and whether it was committed. |
| Runtime failure | Session tool result, worker status, errors, C:\logs\Buffaly logs. | Recover from runtime evidence before touching storage manually. |