Skip to content

feat: Show Enclave sessions started with the CLI - #8

Merged
planger merged 10 commits into
mainfrom
homeshell-enclave-cli-sessions
Nov 13, 2026
Merged

planger merged 10 commits into
mainfrom
homeshell-enclave-cli-sessions

Conversation

@planger

@planger planger commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Enclave sessions started with the enclave CLI now show up in their project, within one inventory
check. A background one is attached and runs as HomeShell's own. One running in a terminal shows as
a limited row: Open opens a shell in its container, Stop ends it in its terminal too (after a
warning), and Restart in HomeShell continues it, attached. Restarting or continuing a CLI session
uses the options Enclave recorded for its container. What a session in a terminal can't do yet is
listed in docs/PROVIDERS.md (GAP 9 to 11).

Also, a session row now offers Stop whenever the session runs, idle and Done included. While a new
session is still starting, Stop cancels the startup after a confirmation. A session that is
restarting offers no Stop.

Last of three stacked PRs, based on #7. The first three commits are daemon, UI and e2e tests, the
fixes from review follow on top.

To try it with Enclave, run enclave run --background in a project folder: it shows up as a normal
row. enclave claude in a terminal shows up as running in a terminal, with Open, Stop and Restart
in HomeShell. Stop on idle and starting sessions also works with the fake provider in
make dev-demo.

Changelog

- Enclave sessions started with the enclave CLI show up in their project. A background one runs
  as HomeShell's own, and one running in a terminal can be opened, stopped or restarted in
  HomeShell.
- Restarting or continuing a CLI session keeps the options it was started with.
- Stop stays available while a session is idle or Done, and cancels a new session that is still
  starting.
- Restarting or continuing an Enclave session that was started without a name keeps its
  conversation.
- Continue no longer stops a session you started again in a terminal under the same name. HomeShell
  shows that session instead.

Checklist

  • Tests added: unit and e2e, or a regression test for a bug fix (see AGENTS.md)
  • Docs updated per the trigger table in AGENTS.md

@tortmayr
tortmayr added this pull request to stack #9 November 12, 2026 15:20
@planger
planger marked this pull request as ready for review November 12, 2026 15:35
@planger
planger requested a review from fismif November 12, 2026 15:36
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from f0ee032 to 33b4cef Compare November 12, 2026 15:40

@EclipseSourceAI EclipseSourceAI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Autonomous AI review. May contain mistakes.

Useful comment? React 👍. Disagree? React 👎 to reject it for follow-up reviews. A reply explaining why helps too.

This agent never approves PRs. A maintainer must sign off.

Only a maintainer can re-request a review from this agent.

Powered by Eclipse Enclave via review-guard-mcp

What it does: HomeShell now picks up Enclave sessions started with the enclave CLI. Each periodic inventory check (inventory.go) runs enclave ps once per directory and shares that listing between drift detection and adoption (adopt.go):

  • Background CLI sessions get a bridge attached and become HomeShell's own sessions.
  • Foreground CLI sessions get a bridgeless Foreground record. Open opens a shell in the container, and Stop asks first because it also ends the session in the user's terminal.
  • Restart in HomeShell continues a foreground session in the background. A restart of an unnamed or auto-numbered container now continues under a new hs- name. The records swap atomically via ReplacingFrom and completeReplacements on load, and the store carries the title and launch config over through Session.Replaces.
  • No recorded settings: a CLI session restarts with the options Enclave recorded for its container (LaunchObserver).
  • Concurrency: the old restarts counter is replaced by per-record generations, so an adoption, foreground end or drift result found by a listing that started before the record was written is discarded.
  • UI: adds per-session capabilities and offers Stop while a session is idle or starting.

Where a maintainer should look:

  • Stop on starting rows: Stop is now also offered on Enclave sessions that are mid-restart, and there it deletes the session instead of stopping it (inline).
  • Open gate: Open skips the liveBridgeRecord check for a foreground session that is restarting (inline).
  • Restart under a new name: the swap and crash-completion path in restart.go, together with the store carry-over in carryOverReplacedLocked, is the riskiest new state machine. The unit tests look thorough, but it deserves a careful read.
  • Daemon vs. UI: the UI hard-codes Enclave-specific "terminal" text even though capabilities is meant to be provider-agnostic.

I could not run the build, the tests or a visual check: this environment has no Go toolchain and no installed webapp dependencies, so I could not start the daemon. This review is from reading the code only.

// A session still starting stops by cancelling its build, which is removing
// its placeholder: no provider has heard of it yet, and nothing is left to
// continue. Offered where Stop will be, once it runs.
const cancellable = Boolean(starting && onStop && onRemove);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

starting isn't only a create placeholder: an Enclave session mid-restart (Continue, Restart with settings, or the new Restart in HomeShell) is projected as starting under its real ID by PrepareRestart. Enclave has sessionStartStop, so that row now gets Stop, and confirming it calls onRemove, which deletes the session and its record rather than stopping it. This should only apply to placeholder rows, ideally with the daemon telling the client which ones those are.

return provider.OpenResult{}, fmt.Errorf("unsupported open mode %q", mode)
}
record, err := p.liveBridgeRecord(ref.SessionID)
if record.takeOver() {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This runs before err is checked. During a restart of a foreground session, beginRestart clears State and Foreground stays set, so takeOver() is true and the ErrSessionStopped from liveBridgeRecord gets dropped. OpenShell then execs into a container that is being stopped and re-run, because the starting projection from SessionState isn't one of the states it refuses. Only fall through to OpenShell when err is ErrCapabilityUnsupported.

// agent's container from others, nothing is adopted.
func (p *Provider) adoptListed(ctx context.Context, listed inventory) bool {
attempted, adopted := false, false
if agentTools, err := p.agentTools(ctx); err != nil {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This runs enclave tools list --json on every inventory check, even when nothing unrecorded is listed, and Tools isn't cached (cli.go). A failure here also blocks re-adopting recorded ended sessions, and adoptionDue doesn't need the tool list for those. Only fetch it once a running unrecorded container comes up.

)}
{!live && (
<p className={styles.rowNote} data-testid="session-outside">
Running in a terminal. HomeShell cannot show its screen or send it

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

capabilities is provider-agnostic, but this note, TAKE_OVER_WARNING and the Restart in HomeShell tooltip all hard-code Enclave's "runs in a terminal" story in the UI. stopWarning already comes from the daemon. The take-over warning and the not-live note should come from it too, so the UI only renders text the provider sends.


// inventoryIntervalFrom reads the interval from the environment's value in milliseconds; a missing or invalid
// one is 0, which falls back to driftCheckInterval.
func inventoryIntervalFrom(value string) time.Duration {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same parse as fakeSessionStartup (serve.go), except without the TrimSpace. One shared helper for these ms test knobs would keep them behaving the same.

planger added a commit that referenced this pull request Nov 12, 2026
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from b136d78 to 936fc4b Compare November 12, 2026 17:32
planger added a commit that referenced this pull request Nov 12, 2026
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
planger added a commit that referenced this pull request Nov 12, 2026
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)

@fismif fismif left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally against a real enclave CLI. Adoption of background and terminal CLI sessions, Open into the container, Stop with the terminal warning, and Stop while starting/idle/Done all work.

Requesting changes for one blocker: Restart in HomeShell / Continue loses the conversation of an unnamed CLI session, which is the default enclave / enclave run --background case, so the PR's main promise ("Restart in HomeShell continues it") fails there.

if unnamed := sessionName == "" || isDigits(sessionName); !unnamed {
return container, sessionName, nil
}
sessionName = newSessionName()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renaming on restart loses the conversation. Enclave keeps a container's ~/.claude per session name (~/.local/state/enclave/projects/<id>/claude/config-store/<name>), so enclave continue under a new hs-… name starts with an empty store, Claude prints No conversation found to continue and exits, and the row turns into "exited right after starting".

Reproduced with a real enclave:

  1. enclave --tool claude (or enclave run --background --tool claude) in a project folder, send one prompt.
  2. Restart in HomeShell (or Stop, then Continue from Ended).
  3. Error row; the conversation is still in config-store/default/, while config-store/hs-…/ is empty.

For a terminal session this is the worst case: the take-over has already ended the session in the user's terminal. The e2e suite uses a fake enclave, so it can't see this.

Options: keep the name for a restart (accepting that the default container is taken), or have the new hs- session use the old name's config store, if Enclave can do that (an Enclave flag/gap?). Only unnamed and auto-numbered containers are affected: restartNames keeps any other session name, so a --name foo session (and HomeShell's own hs- sessions) restarts with the same config store and keeps its conversation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for reproducing this with a real enclave! Fixed in 42b6ff6. A restart that continues the conversation now keeps the session's name (the default container included), so enclave continue finds the conversation store. Only a fresh restart of an unnamed container still gets a new hs- name. The fake enclave in the unit and e2e tests now keeps one conversation per name, so a continue under another name fails there too.

if !listedWithout || listFailed {
continue
}
record.State, record.Error = domain.SessionDone, ""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Marking a foreground row Done here combines badly with takeDown in restart.go, which always stops the old container name ("Always stopped: an ended state may have been inferred from a listing…"). A terminal row turns Done once a listing misses its container, after which takeOver() is false and no warning is shown. If the user starts enclave --tool claude again in the same folder, the default container name is reused, and Continue on the old Done row before the next inventory check stops the user's new terminal session without a warning. Could the stop be skipped (or warned) when the name is listed as running a container this record didn't start?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, good catch! Fixed in 42b6ff6. Before a restart or Continue of an ended session, the provider now lists the project's containers. If the session's container name runs again, it refuses with a 409 ("This session is running again, started outside HomeShell. It shows here as running in a moment.") and doesn't stop anything. The next inventory check then adopts the new session. There is still a small window between that listing and the stop, though.

planger added a commit that referenced this pull request Nov 13, 2026
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from 936fc4b to 3639f91 Compare November 13, 2026 09:29
planger added a commit that referenced this pull request Nov 13, 2026
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from 3639f91 to f815ade Compare November 13, 2026 10:06
planger added a commit that referenced this pull request Nov 13, 2026
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
…name running again alone

Enclave keeps an agent's conversation per session name, so continuing an
unnamed session (the default container, or an auto-numbered one) under a
new hs- name found no conversation and the agent exited. A restart that
continues now keeps the name; only a fresh restart of an unnamed session
takes a new hs- name. The fake enclave in the unit and e2e tests keeps a
conversation per name, so a continue under another name fails there too.

Continue of an ended session stopped its container name first, which a
new session the user started in a terminal may hold again. It is now
refused while that name runs, and the next inventory check adopts the
new session.

#8 (comment)
#8 (comment)
@planger

planger commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Re your review: both points are addressed, see the two threads. Restart in HomeShell and Continue of an unnamed session now keep the name and thus the conversation. Thanks for testing this against a real enclave!

@fismif
fismif self-requested a review November 13, 2026 10:47

@fismif fismif left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for addressing the raised points. LGTM!

planger added a commit that referenced this pull request Nov 13, 2026
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from 42b6ff6 to acb6166 Compare November 13, 2026 11:49
planger added a commit that referenced this pull request Nov 13, 2026
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)
planger added a commit that referenced this pull request Nov 13, 2026
…name running again alone

Enclave keeps an agent's conversation per session name, so continuing an
unnamed session (the default container, or an auto-numbered one) under a
new hs- name found no conversation and the agent exited. A restart that
continues now keeps the name; only a fresh restart of an unnamed session
takes a new hs- name. The fake enclave in the unit and e2e tests keeps a
conversation per name, so a continue under another name fails there too.

Continue of an ended session stopped its container name first, which a
new session the user started in a terminal may hold again. It is now
refused while that name runs, and the next inventory check adopts the
new session.

#8 (comment)
#8 (comment)
Base automatically changed from homeshell-untracked-worktrees to main November 13, 2026 12:12
Enclave sessions started with the enclave CLI show up in their project
within one inventory check, if they run an agent tool profile and nothing
else holds them. A background one is attached and runs as HomeShell's own.
A foreground one, running in the user's terminal, is listed with limited
capabilities: Open opens a shell in its container, Stop ends it in its
terminal too, and Restart in HomeShell continues it attached.

Sessions can carry capabilities of their own, and a session can replace
another: a restart of an unnamed container goes on under a new HomeShell
name, and the row keeps its title and settings. Why: the default container
stays free for the next enclave start in a terminal. A CLI session has no
recorded launch config, so its restart or Continue replays the options
Enclave recorded for the container. docs/PROVIDERS.md lists what is not
supported yet (GAP 9 to 11).
…s or starts

A session running in a terminal says so, warns before Stop or Restart with
settings ends it there, and offers Restart in HomeShell.

A session row offers Stop whenever the session has a runtime behind it
(idle, shown as Done, unknown, running or waiting): before, Stop went away
once the agent went idle, though its container still ran. While a session
starts, Stop cancels its startup after a confirmation, as Delete asks one,
and the row goes.
Covers adopting background and foreground CLI sessions, attaching each
once, restarting them in HomeShell, a CLI session in an untracked worktree,
and Stop on idle and starting sessions.
Open fell through to a shell for a foreground session before checking why
the bridge record was not live, so a restart's ErrSessionStopped was dropped
and the shell exec'd into a container being stopped and run again.

#8 (comment)
Every inventory check ran `enclave tools list` even when nothing unrecorded
was listed, and a failure to list them also blocked adopting a recorded,
ended session again, which needs no tool profiles.

#8 (comment)
HOMESHELL_ENCLAVE_INVENTORY_MS and HOMESHELL_FAKE_SESSION_STARTUP_MS were
parsed by two copies of the same code, one without the whitespace trim.
envutil.Milliseconds reads both.

#8 (comment)
A session restarting is projected as starting under its own ID, so the row
offered Stop there too, and confirming it deleted the session and its record
rather than stopping it. The daemon now marks its placeholder rows
(placeholder: true), and only those cancel on Stop.

#8 (comment)
The UI hard-coded Enclave's "runs in a terminal" text for the row's note, the
Restart in HomeShell confirmation and tooltip, and the restart dialog. The
session's capabilities now carry takeOverWarning and note beside stopWarning,
and the UI renders what the provider sends.

#8 (comment)
…renamed meanwhile or not

The session that replaces another takes over its title and launch config
also when the old one was renamed while the pass that found the
replacement ran.
…name running again alone

Enclave keeps an agent's conversation per session name, so continuing an
unnamed session (the default container, or an auto-numbered one) under a
new hs- name found no conversation and the agent exited. A restart that
continues now keeps the name; only a fresh restart of an unnamed session
takes a new hs- name. The fake enclave in the unit and e2e tests keeps a
conversation per name, so a continue under another name fails there too.

Continue of an ended session stopped its container name first, which a
new session the user started in a terminal may hold again. It is now
refused while that name runs, and the next inventory check adopts the
new session.

#8 (comment)
#8 (comment)
@planger
planger force-pushed the homeshell-enclave-cli-sessions branch from acb6166 to 8ba147e Compare November 13, 2026 12:12
@planger
planger merged commit 82c643d into main Nov 13, 2026
6 checks passed
@planger
planger deleted the homeshell-enclave-cli-sessions branch November 13, 2026 12:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants