Delivering code and checking results

A Session finishing its code does not mean the change reached GitHub. aachat does not automatically commit, push, or create PRs, and PRs and pushes are not recorded automatically either. When checking results, confirm not only the change and its verification but also which repository, which branch or PR, and which HEAD it reached.

Project documents, Media, HTML, Workflows, and Triggers are saved through their own save and sync mechanisms and recorded as Session results automatically. This page covers delivering Git-managed code and Agent capabilities.

Two repositories and their targets

Before starting, check the Session's repository, its target, and the target repository's instructions. The Team default repo, the Project's working branch, and the currently checked-out Session branch are not the same. Do not skip a requested PR and push to main instead.

aachat/ and .aachat/ are git-excluded in the workspace. Do not commit Project sync files or generated contracts to the Workspace repo. See Shared Documents for documents and Environment for environment settings.

Agents deliver and record

These steps are for Agents inside a Session started by aachat. In an outside terminal or coding agent, do not use chat; use ordinary Git/GitHub operations.

1. Commit

Read git status and git diff, and commit only the files related to this work. Follow the repository's tests. Do not commit credentials, absolute paths, or environment-specific values.

git status --short --branch
git diff
git add path/to/changed-file
git commit -m "Describe the completed change"

2. Push, and create a PR if needed

When delivering to the Project's working branch, replace <working-branch> with the confirmed target. On a non-fast-forward, run git fetch origin and git rebase origin/<working-branch>, then push again.

git push origin HEAD:<working-branch>

When delivering with a PR, push the Session branch and create the PR. Before creating it, check the target repository's Pull Request template and repository guidance. If a template exists, follow it and keep its structure and required items. Replace main with the target repository's base branch. To fix an existing PR, push to that PR's head branch; do not recreate the PR.

git push -u origin HEAD
gh pr create --base main --title "Describe the change" --body-file pr-body.md

3. Record it right away

As soon as PR creation or a push in the workspace repo succeeds, record it once; do not wait for the Session to end. Put the PR URL in ref for a PR, or the remote branch you actually pushed as git-branch:<owner/repo>:<branch> for a push without a PR.

chat result report --stdin <<'JSON'
{"results":[{"ref":"https://github.com/owner/repo/pull/123"}]}
JSON

chat result report --stdin <<'JSON'
{"results":[{"ref":"git-branch:owner/repo:feature-branch"}]}
JSON

Replace the example values with the actual target. chat result report --help shows the input details.

• 1 to 50 items per call. The only top-level field is results; each item holds ref, key, summary, inputs, excluded, and project
• A PR or branch item needs only ref; summary is optional. Recording a PR means you do not need to record the push to its head branch separately
• The repository must be this Session's workspace repo or agent repo. Any other repository is rejected with delivery_repository_mismatch
• Recording reads neither local Git nor GitHub. It saves the ref you send, and it does not push or create PRs for you
• The Project is inferred from the current accepted task. If it cannot be inferred you get project_required; only then add --project <team/project> or a per-item project
• The former delivery item field was removed; use ref instead. The current CLI rejects the unknown field locally as item invalid_input in data.items[]. If old input reaches the server, the item code is invalid_report (delivery input was removed: …). Neither is necessarily the whole request's code. If an old CLI sends it, run aachat update

The Agent repo is a separate Git worktree with a detached HEAD. After reviewing and committing, push from that directory to main. At the end of the turn, the launcher automatically records the push as a result when HEAD includes Session commits and is contained in the local origin/main tracking ref.

cd "$AA_AGENT_DIR"
git status --short --branch
git diff
# add and commit the related files, then run
git push origin HEAD:main
git remote get-url origin

A ref already recorded does not need to be reported again; reporting it again changes nothing. A record saves your declaration of the delivery; it is not a GitHub-verified result and does not push or create PRs for you.

Read the report result

On success, data.items returns each item's status (created, updated, unchanged). If any item is not recorded, the response is ok:false with exit code 1 and error.code result_report_incomplete. Recorded items are saved and remain in data.items.

An item that was not recorded has status error and carries code, message, retryable, and input_index, and may include diagnostic.

None of these proves that the GitHub push failed. Do not repeat the push or PR creation to fix a record. If the whole request fails with session_not_running, you reported from outside a turn that the Session accepted for execution (Troubleshooting).

Resend only the report

When items were not recorded after sending, data.retry_file returns the path of the fixed payload saved before sending (a file with mode 0600 under .aachat/session-results/pending/ in AA_WS_DIR). Resend that file unedited:

chat result report --retry-stdin < <path from data.retry_file>

A resend keeps the Project, version, and nonce fixed. Re-running the original JSON with --stdin is not a resend but a new update. Items rejected before sending (such as invalid_ref or document_not_synced) are not in retry_file; fix only those items and report them again with --stdin. Do not re-run the push or PR creation. State any remaining failure briefly in the final answer. A reporting failure alone does not block the Session from ending.

Curate results and read past deliveries

Right before a final answer with deliverables, curate your Session's results (Sessions). For an existing result you can add or change its summary, or update only inputs without summary. Hide unneeded results such as drafts or duplicates from ordinary lists with "excluded":true, and restore with false (null is invalid). Excluding only tidies lists; the body, references, and delivery records are not removed.

Check recorded PRs and pushes in the github_pr and git_branch results of chat result list. The local state in repositories is a record at observation time. If there is no delivery record or it cannot be read, treat it as unconfirmed.

What people should check

Open the Session from the Project's Work Panel and check the result badges in its header.

• The Pull requests badge opens the recorded PRs, from which you can go to the GitHub PR
• The Branches badge opens the branch pushes recorded without a PR
• The Code delivery badge opens the local repository observation. When a repository needs attention it uses the attention color with a label such as 3 uncommitted changes, Local inspection failed, or 2 repos need attention. Session list rows show only this attention

The Code delivery panel shows, per repository, Needs attention, Next: (the next action), and Technical details (uncommitted change count, Session commit count, Current branch, and the failure Reason). Without a recorded delivery it shows No recorded submissions.

1. Check that the PR or branch matches the requested repository and target.
2. Compare the delivered HEAD with the change and verification in scope. If changes were added after delivery, check that they also arrived.
3. Read the PR description and check results for unverified points and remaining work.
4. For work that needs merge, release, or post-release checks, confirm each of those results.

A delivery record does not prove CI success, review approval, merge, or production rollout. A stopped Session or a "done" message does not substitute for them.

Local observation and attention

At the end of a turn, local observation checks, read-only, for uncommitted changes and the Session commit count. It does not fetch from the remote or query GitHub, so do not conclude delivery from local observation alone. If nothing is shown or it cannot be read, do not assume there are no changes.

Local observation does not decide whether anything was delivered. Remaining Session commits do not raise attention, so check together with the PR and push records that the requested change reached its target.

Main Reasons for Local inspection failed:

If you made new commits after an older delivery, a past PR record does not mean the latest changes were delivered. Check the remote state too.

Before ending the Session

The working workspace is not permanent storage. Only work that was committed and pushed to the requested branch or PR remains. State whether the work is pushed, not pushed, or has no repository changes, and hand over the PR URL or branch, the tests you ran, and any remaining gap. If it is not pushed, explain the remaining changes and the next action needed.

After chat session finish, one final wrap-up turn (Asset Wrap-Up) runs after the current turn. There, record only PRs and pushes that are not yet recorded with chat result report --stdin; do not resend recorded ones.

At Asset Wrap-Up input time, Sessions with a workspace repository also inspect tracked paths in the local HEAD. If the commit tracks anything under aachat/ (including aachat itself) except aachat/README.md, the agent’s repository status lists the forbidden paths and warns that the next Session cannot start from this commit. The diagnostic supports keeping shared files on disk, removing them from tracking, and committing and pushing within the existing delivery permissions. It does not repair files or prevent completion. Staged removal alone leaves HEAD unchanged. Failed checks are shown as unavailable. The absence of a warning does not guarantee remote or other-branch state, commits made during the final turn, or overall startup success.

See Sessions for workspace retention, reclamation, and resuming Sessions, Projects for accepting Project results, and CLI for syntax.