Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: reconcile stale submodule checkouts without an agent

[._.]/ Adam Eivy5903d2555b6d
diff --git a/client/src/components/apps/tabs/RepositorySourcePanel.jsx b/client/src/components/apps/tabs/RepositorySourcePanel.jsx
index 6d6d391eac..e2831f9046 100644
--- a/client/src/components/apps/tabs/RepositorySourcePanel.jsx
+++ b/client/src/components/apps/tabs/RepositorySourcePanel.jsx
@@ -106,7 +106,7 @@ function RepositoryCard({ source }) {
{source.branch || 'detached'} @ {source.shortHead || 'unknown'}
</code>
<span className={source.clean === false ? 'text-port-warning' : 'text-gray-500'}>
- {source.clean === true ? 'clean checkout' : source.clean === false ? 'local changes' : 'worktree unknown'}
+ {source.submodulesOnly ? 'submodules need updating' : source.clean === true ? 'clean checkout' : source.clean === false ? 'local changes' : 'worktree unknown'}
</span>
</div>
@@ -240,7 +240,8 @@ export default function RepositorySourcePanel({ appId, appName, onUpdated, refre
|| (source.origin?.isFork && source.forkVsUpstream?.available === false)
));
const canUpdate = sources.every((source) => source.present) && status?.updatePullsAll;
- const needsRecovery = hasLocalChanges || sources.some(source => source.clean === false || source.localVsOrigin?.state === 'diverged');
+ const needsRecovery = (hasLocalChanges && !primary?.submodulesOnly)
+ || sources.some(source => (source.clean === false && !source.submodulesOnly) || source.localVsOrigin?.state === 'diverged');
const shouldOfferUpdate = status?.updateAvailable || remoteUnknown;
const primaryLabel = forkNeedsSync
? 'Sync fork & update app'
diff --git a/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx b/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx
index 79a324ef74..e0c1527e17 100644
--- a/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx
+++ b/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx
@@ -112,6 +112,19 @@ beforeEach(() => {
afterEach(() => cleanup());
describe('managed app repository sources', () => {
+ it('updates stale submodules through the managed flow without a recovery agent', async () => {
+ const status = canonicalStatus();
+ status.sources = [{ ...status.sources[0], clean: false, submodulesOnly: true, localVsOrigin: { ahead: 0, behind: 0, state: 'current' } }];
+ api.getAppRepositorySources.mockResolvedValue(status);
+ render(<RepositorySourcePanel appId="portos-default" appName="PortOS" hasLocalChanges />);
+ expect(await screen.findByText('submodules need updating')).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Resolve with agent' })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Update app' }));
+ fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Update app' }));
+ expect(useAppOperation().startUpdate).toHaveBeenCalledWith('portos-default', 'PortOS', { syncFork: false });
+ expect(api.addCosTask).not.toHaveBeenCalled();
+ });
+
it('explains and versions both independent checkouts', async () => {
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
diff --git a/docs/SELF_UPDATE.md b/docs/SELF_UPDATE.md
index 29b2067763..02f8972edd 100644
--- a/docs/SELF_UPDATE.md
+++ b/docs/SELF_UPDATE.md
@@ -190,12 +190,19 @@ non-conflicting local changes. The unattended readiness gate refuses until the
checkout is on the default branch and clean, because a stash nobody is told
about reads as lost work.
-Two remedies run without asking, because neither can destroy work:
+These remedies run without asking, because they preserve local work:
- **switch to the default branch** from a CLEAN feature branch (the commits stay on the
branch ref), and
- **restore modified auto-generated lockfiles** (`npm install` rewrites them; the update
- reinstalls anyway). Restored by explicit path, never `-- .`.
+ reinstalls anyway). Restored by explicit path, never `-- .`, and
+- **update stale submodule checkouts to their parent gitlinks** when the checkouts
+ are clean ancestors of the pins, including recursively stale children. Staged
+ gitlinks, edits, untracked files, ahead/divergent commits and unreadable state
+ remain blockers. Repository Sources uses the same read-only classification to
+ offer **Update app** for this drift, even when the parent is already current,
+ rather than requiring **Resolve with agent**. The managed updater then runs
+ its existing pinned submodule update; it never uses `--remote` or `--force`.
Everything else — uncommitted work, a local commit not on origin, an interrupted
rebase/merge, conflict markers — queues ONE high-priority CoS task (deduped on a constant
diff --git a/server/services/gitPinnedSubmodules.js b/server/services/gitPinnedSubmodules.js
new file mode 100644
index 0000000000..f9f59ac866
--- /dev/null
+++ b/server/services/gitPinnedSubmodules.js
@@ -0,0 +1,39 @@
+import { join } from 'path';
+import { execGitSafe } from '../lib/execGit.js';
+
+/**
+ * Read-only classification of stale gitlinks. Only clean checkouts at an
+ * ancestor of the parent's pin are mechanical repairs. Staged pointers, local
+ * commits, edits, untracked files and unreadable state retain the dirty guard.
+ * Porcelain v2's NUL framing preserves spaces and non-ASCII submodule paths.
+ */
+export async function inspectPinnedSubmoduleDrift(repoPath) {
+ const status = await execGitSafe([
+ 'status', '--porcelain=v2', '-z', '--ignore-submodules=none', '--untracked-files=all',
+ ], repoPath, { env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
+ if (status.exitCode !== 0) return { repairablePaths: [], onlyRepairable: false };
+
+ const records = status.stdout.split('\0').filter(Boolean);
+ const repairablePaths = [];
+ for (const record of records) {
+ // Ordinary, unstaged gitlink changes only. The index must still match HEAD.
+ const match = /^1 \.M S[C.][M.][U.] 160000 160000 160000 ([a-f0-9]+) \1 (.+)$/s.exec(record);
+ if (!match) continue;
+ const [, pin, path] = match;
+ const dir = join(repoPath, path);
+ const head = await execGitSafe(['rev-parse', '--verify', 'HEAD'], dir);
+ if (head.exitCode !== 0) continue;
+ if (head.stdout.trim() !== pin) {
+ const ancestor = await execGitSafe(['merge-base', '--is-ancestor', 'HEAD', pin], dir);
+ if (ancestor.exitCode !== 0) continue;
+ }
+ const nested = await inspectPinnedSubmoduleDrift(dir);
+ // A clean submodule has no records; recursively stale children are safe too.
+ if (nested.clean || nested.onlyRepairable) repairablePaths.push(path);
+ }
+ return {
+ clean: records.length === 0,
+ repairablePaths,
+ onlyRepairable: records.length > 0 && repairablePaths.length === records.length,
+ };
+}
diff --git a/server/services/managedAppRepositories.js b/server/services/managedAppRepositories.js
index d2a3a368c1..ab11b058e2 100644
--- a/server/services/managedAppRepositories.js
+++ b/server/services/managedAppRepositories.js
@@ -7,6 +7,7 @@ import { execGitSafe, fetchOrigin, isFetchFresh, resolveForgeForRepo } from './g
import { execGh } from './github.js';
import { forgeMissingScopesOf } from '../lib/forgeAccessErrors.js';
import { forgeScopeMissingError } from './forgeScopeRefresh.js';
+import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';
const GH_TIMEOUT_MS = 60_000;
@@ -174,6 +175,8 @@ async function inspectCheckout({ id, label, repoPath }) {
const branch = branchName && branchName !== 'HEAD' ? branchName : null;
const head = headResult.exitCode === 0 ? headResult.stdout.trim() : null;
const clean = worktreeResult.exitCode === 0 ? worktreeResult.stdout.trim().length === 0 : null;
+ const submodulesOnly = clean === false
+ && (await inspectPinnedSubmoduleDrift(repoPath)).onlyRepairable;
// Skip the network hop when this checkout's remote refs were already
// refreshed inside the freshness window — the refs really are current, so
// `fresh: true` stays truthful. This read used to be reachable only from the
@@ -205,6 +208,7 @@ async function inspectCheckout({ id, label, repoPath }) {
head,
shortHead: head?.slice(0, 7) || null,
clean,
+ submodulesOnly,
origin: {
...topology.origin,
url: topology.origin.originUrl,
@@ -287,7 +291,7 @@ export async function getManagedAppRepositorySources(app) {
// its own origin, plus a fork behind upstream that PortOS is allowed to
// fast-forward. A fork PortOS can only read stays visible on the Git tab
// but never claims an update is available.
- updateAvailable: sources.some((source) => source.localVsOrigin?.behind > 0
+ updateAvailable: sources.some((source) => source.submodulesOnly || source.localVsOrigin?.behind > 0
|| (source.forkSyncable && (source.forkVsUpstream?.behind || 0) > 0)),
updatePullsAll: true,
updateRestartsApp: Array.isArray(app?.pm2ProcessNames) && app.pm2ProcessNames.length > 0,
diff --git a/server/services/managedAppRepositories.test.js b/server/services/managedAppRepositories.test.js
index a2c0b460fb..3c5a7438d8 100644
--- a/server/services/managedAppRepositories.test.js
+++ b/server/services/managedAppRepositories.test.js
@@ -9,6 +9,7 @@ const mock = vi.hoisted(() => ({
isFetchFresh: vi.fn(),
resolveForgeForRepo: vi.fn(),
execGh: vi.fn(),
+ inspectPinnedSubmoduleDrift: vi.fn(),
}));
vi.mock('../lib/fileUtils.js', async (importOriginal) => ({
@@ -27,6 +28,7 @@ vi.mock('./git.js', () => ({
resolveForgeForRepo: mock.resolveForgeForRepo,
}));
vi.mock('./github.js', () => ({ execGh: mock.execGh }));
+vi.mock('./gitPinnedSubmodules.js', () => ({ inspectPinnedSubmoduleDrift: mock.inspectPinnedSubmoduleDrift }));
import {
getManagedAppRepositorySources,
@@ -52,6 +54,7 @@ const forkOrigin = {
describe('managed app repository topology', () => {
beforeEach(() => {
vi.clearAllMocks();
+ mock.inspectPinnedSubmoduleDrift.mockResolvedValue({ repairablePaths: [], onlyRepairable: false });
mock.pathExists.mockResolvedValue(true);
mock.getOriginInfo.mockResolvedValue(forkOrigin);
mock.readRemoteUrl.mockResolvedValue(null);
@@ -140,6 +143,19 @@ describe('managed app repository topology', () => {
expect(mock.fetchOrigin).toHaveBeenCalledWith(REPO);
});
+ it('offers an update for stale submodules even when the parent is current', async () => {
+ mock.execGit.mockImplementation(async (args) => {
+ if (args[0] === 'status') return { exitCode: 0, stdout: ' M lib/dep\n' };
+ if (args[0] === 'rev-list') return { exitCode: 0, stdout: '0\t0\n' };
+ return { exitCode: 0, stdout: args.includes('--abbrev-ref') ? 'main\n' : `${'1'.repeat(40)}\n` };
+ });
+ mock.execGh.mockResolvedValue('{}');
+ mock.getOriginInfo.mockResolvedValue({ ...forkOrigin, isUpstream: true });
+ mock.inspectPinnedSubmoduleDrift.mockResolvedValue({ repairablePaths: ['lib/dep'], onlyRepairable: true });
+ const result = await getManagedAppRepositorySources(app);
+ expect(result).toMatchObject({ updateAvailable: true, sources: [{ clean: false, submodulesOnly: true }] });
+ });
+
// The Eidoverse page runs this read on every visit, so an ungated fetch would
// be a network hop per mount for refs that were just refreshed.
it('skips the network fetch for refs already refreshed inside the freshness window', async () => {
diff --git a/server/services/updateRepoReadiness.js b/server/services/updateRepoReadiness.js
index 5f5e0a65e1..30a23f5366 100644
--- a/server/services/updateRepoReadiness.js
+++ b/server/services/updateRepoReadiness.js
@@ -11,13 +11,15 @@
*
* So the auto-updater refuses to start until the checkout is ON the default
* branch and CLEAN, and this module is what decides that — plus what can be put
- * right mechanically. Two remedies are safe enough to run unattended, because
- * neither can destroy work:
+ * right mechanically. These remedies are safe enough to run unattended, because
+ * each preserves local work:
*
* - checking out the default branch from a CLEAN feature branch (the commits
* stay on the branch ref; nothing is discarded), and
* - restoring modified auto-generated lockfiles (`npm install` rewrites them
- * as a side effect, and the update reinstalls anyway).
+ * as a side effect, and the update reinstalls anyway), and
+ * - checking out pinned submodule commits when their current checkouts are
+ * clean ancestors of those pins (including recursively stale children).
*
* Everything else — uncommitted work, an unpushed commit, an interrupted
* rebase/merge, conflict markers — is judgement no script should make on a
@@ -33,6 +35,7 @@ import * as gitService from './git.js';
import { countAheadBehind, detectOperationInProgress } from './repoSync.js';
import { classifyWorktreeDirt } from './worktreeManager.js';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
+import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';
/** First line of the repair task — stable so `addTask`'s dedup collapses reruns. */
export const REPO_REPAIR_TASK_DESCRIPTION = 'Restore the PortOS checkout to a clean default branch so automatic updates can run';
@@ -57,6 +60,7 @@ const REASON_LABELS = {
const REPAIRABLE_LABELS = {
'restore-lockfiles': 'auto-generated lockfiles need restoring',
'checkout-default': 'the checkout needs switching back to the default branch',
+ 'update-submodules': 'submodule checkouts need updating to their pinned commits',
};
const describe = (code) => REASON_LABELS[code] || REPAIRABLE_LABELS[code] || code;
@@ -99,7 +103,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})
return {
repoPath: dir,
branch: null, defaultBranch: null, interrupted: null, ahead: null, behind: null,
- lockfilePaths: [],
+ lockfilePaths: [], submodulePaths: [],
...fields,
reasons,
repairable,
@@ -146,7 +150,10 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})
return verdict({ defaultBranch, reasons: ['git-unreadable'] });
}
- const dirt = classifyWorktreeDirt(porcelain);
+ const { repairablePaths: submodulePaths } = porcelain.trim()
+ ? await inspectPinnedSubmoduleDrift(dir)
+ : { repairablePaths: [] };
+ const dirt = classifyWorktreeDirt(porcelain, { ignoredPaths: submodulePaths });
const conflicted = porcelain.split('\n').some((line) => /^(DD|AU|UD|UA|DU|AA|UU) /.test(line));
const detached = branch === 'HEAD';
const onDefaultBranch = Boolean(defaultBranch) && branch === defaultBranch;
@@ -166,6 +173,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})
if (conflicted) reasons.push('conflicted-files');
if (dirt.hasRealChanges) reasons.push('uncommitted-changes');
else if (!dirt.clean) repairable.push('restore-lockfiles');
+ if (submodulePaths.length) repairable.push('update-submodules');
if (detached) reasons.push('detached-head');
else if (defaultBranch && !onDefaultBranch) {
// A clean feature branch is a mechanical checkout away from ready; a dirty
@@ -193,6 +201,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})
ahead,
behind,
lockfilePaths: dirt.lockfilePaths,
+ submodulePaths,
reasons,
repairable,
});
@@ -212,9 +221,16 @@ export async function prepareUpdateRepo({ repoPath = PATHS.root } = {}) {
// No fetch: the one caller reads with `fetch: true` before its idle gate and
// then calls this, so a second network hop would only re-answer that read.
const before = await checkUpdateRepoReadiness({ repoPath: dir, fetch: false });
- if (before.ready || before.repairable.length === 0) return { verdict: before, actions: [] };
+ if (before.ready || before.reasons.length || before.repairable.length === 0) return { verdict: before, actions: [] };
const actions = [];
+ if (before.repairable.includes('update-submodules')) {
+ const sync = await execGitSafe(['submodule', 'sync', '--recursive'], dir);
+ const update = sync.exitCode === 0 && await execGitSafe([
+ 'submodule', 'update', '--init', '--recursive', '--checkout', '--', ...before.submodulePaths,
+ ], dir, { timeout: 120000 });
+ if (update.exitCode === 0) actions.push('updated submodules to their pinned commits');
+ }
if (before.repairable.includes('restore-lockfiles') && before.lockfilePaths.length) {
// By explicit path, never `-- .`: the classifier proved these specific
// paths are auto-generated lockfiles, and a pathspec of `.` would discard
diff --git a/server/services/updateRepoReadiness.test.js b/server/services/updateRepoReadiness.test.js
index 7bad32cd8f..7d44730c49 100644
--- a/server/services/updateRepoReadiness.test.js
+++ b/server/services/updateRepoReadiness.test.js
@@ -40,6 +40,24 @@ function makeRepo() {
return clone;
}
+function makeStaleSubmodule() {
+ const dependency = makeRepo();
+ const repo = makeRepo();
+ const path = 'lib/dép with spaces';
+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'add', dependency, path);
+ git(repo, 'commit', '-am', 'add dependency');
+ writeFileSync(join(dependency, 'README.md'), 'new dependency revision\n');
+ git(dependency, 'commit', '-am', 'advance dependency');
+ const pin = git(dependency, 'rev-parse', 'HEAD').trim();
+ const checkout = join(repo, path);
+ git(checkout, 'fetch', 'origin');
+ // Same state as pulling a parent gitlink bump without updating submodules.
+ git(repo, 'update-index', '--cacheinfo', `160000,${pin},${path}`);
+ git(repo, 'commit', '-m', 'pin new dependency');
+ git(repo, 'push', 'origin', 'main');
+ return { repo, checkout, pin, path };
+}
+
beforeEach(() => vi.restoreAllMocks());
// Fail-fast cancellation can finish Vitest's wrapper while its Git subprocess
// still owns the checkout. Drain those bodies before deleting the fixtures.
@@ -50,6 +68,55 @@ afterAll(async () => {
});
describe('update repo readiness', () => {
+ it('repairs a clean stale submodule without an agent, even with quoted paths', async () => {
+ const { repo, checkout, pin, path } = makeStaleSubmodule();
+ const before = await checkUpdateRepoReadiness({ repoPath: repo });
+ expect(before).toMatchObject({ ready: false, needsAgent: false, reasons: [], repairable: ['update-submodules'], submodulePaths: [path] });
+ const { verdict, actions } = await prepareUpdateRepo({ repoPath: repo });
+ expect(verdict.ready).toBe(true);
+ expect(actions).toEqual(['updated submodules to their pinned commits']);
+ expect(git(checkout, 'rev-parse', 'HEAD').trim()).toBe(pin);
+ });
+
+ it('repairs a stale nested checkout without moving its already-pinned parent', async () => {
+ const { repo: dependency, checkout, pin, path } = makeStaleSubmodule();
+ const old = git(checkout, 'rev-parse', 'HEAD').trim();
+ const repo = makeRepo();
+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'add', dependency, 'lib/outer');
+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'update', '--init', '--recursive');
+ git(repo, 'commit', '-am', 'add nested dependency');
+ git(repo, 'push', 'origin', 'main');
+ const outer = join(repo, 'lib/outer');
+ const nested = join(outer, path);
+ const outerHead = git(outer, 'rev-parse', 'HEAD');
+ git(nested, 'checkout', old);
+ const { verdict } = await prepareUpdateRepo({ repoPath: repo });
+ expect(verdict).toMatchObject({ ready: true, needsAgent: false });
+ expect(git(nested, 'rev-parse', 'HEAD').trim()).toBe(pin);
+ expect(git(outer, 'rev-parse', 'HEAD')).toBe(outerHead);
+ });
+
+ for (const kind of ['edit', 'untracked', 'staged-pointer', 'local-commit']) it(`preserves submodule ${kind} as real work`, async () => {
+ const { repo, checkout, pin, path } = makeStaleSubmodule();
+ if (kind === 'edit') writeFileSync(join(checkout, 'README.md'), 'local edit\n');
+ if (kind === 'untracked') writeFileSync(join(checkout, 'local.txt'), 'local file\n');
+ if (kind === 'staged-pointer') git(repo, 'add', path);
+ if (kind === 'local-commit') {
+ git(checkout, 'checkout', pin);
+ git(checkout, 'config', 'user.email', '[email protected]');
+ git(checkout, 'config', 'user.name', 'Example Tester');
+ writeFileSync(join(checkout, 'README.md'), 'local commit\n');
+ git(checkout, 'commit', '-am', 'unpublished dependency work');
+ }
+ const head = git(checkout, 'rev-parse', 'HEAD');
+ const status = git(repo, 'status', '--porcelain');
+ const { verdict, actions } = await prepareUpdateRepo({ repoPath: repo });
+ expect(verdict).toMatchObject({ ready: false, needsAgent: true, reasons: ['uncommitted-changes'] });
+ expect(actions).toEqual([]);
+ expect(git(checkout, 'rev-parse', 'HEAD')).toBe(head);
+ expect(git(repo, 'status', '--porcelain')).toBe(status);
+ });
+
it('reports a clean checkout on the default branch as ready', async () => {
const verdict = await checkUpdateRepoReadiness({ repoPath: makeRepo() });
expect(verdict).toMatchObject({ ready: true, needsAgent: false, branch: 'main', defaultBranch: 'main', reasons: [], repairable: [] });